// 版权所有2011 Go作者。版权所有。
// 此源代码的使用受BSD样式的约束
// 可以在许可证文件中找到的许可证。

// 包sql提供了一个围绕sql（或类似sql）的通用接口
// 数据库。
// None
// sql包必须与数据库驱动程序结合使用。
// 请参阅https:
// None
// 不支持上下文取消的驱动程序在
// 查询完成后。
// None
// 有关用法示例，请参见
// https:
package sql

import (
	"context"
	"database/sql/driver"
	"errors"
	"fmt"
	"io"
	"reflect"
	"runtime"
	"sort"
	"strconv"
	"sync"
	"sync/atomic"
	"time"
)

var (
	driversMu sync.RWMutex
	drivers   = make(map[string]driver.Driver)
)

// nowFunc返回当前时间；它在测试中被覆盖。
var nowFunc = time.Now

// Register通过提供的名称使数据库驱动程序可用。
// 如果使用相同的名称调用寄存器两次，或者如果驱动程序为零，
// 它恐慌了。
func Register(name string, driver driver.Driver) {
	driversMu.Lock()
	defer driversMu.Unlock()
	if driver == nil {
		panic("sql: Register driver is nil")
	}
	if _, dup := drivers[name]; dup {
		panic("sql: Register called twice for driver " + name)
	}
	drivers[name] = driver
}

func unregisterAllDrivers() {
	driversMu.Lock()
	defer driversMu.Unlock()
	// 用于测试。
	drivers = make(map[string]driver.Driver)
}

// Drivers返回已注册驱动程序名称的排序列表。
func Drivers() []string {
	driversMu.RLock()
	defer driversMu.RUnlock()
	list := make([]string, 0, len(drivers))
	for name := range drivers {
		list = append(list, name)
	}
	sort.Strings(list)
	return list
}

// NamedArg是一个命名参数。NamedArg值可以用作
// Query或Exec的参数，并绑定到相应的命名
// SQL语句中的参数。
// None
// 有关创建NamedArg值的更简洁的方法，请参见
// 指定的函数。
type NamedArg struct {
	_Named_Fields_Required struct{}

	// Name是参数占位符的名称。
	// None
	// 如果为空，参数列表中的序号位置将为
	// 习惯于
	// None
	// 名称必须省略任何符号前缀。
	Name string

	// Value是参数的值。
	// 可以为其指定与查询相同的值类型
	// 论据。
	Value interface{}
}

// Named提供了一种更简洁的方法来创建NamedArg值。
// None
// 用法示例：
// None
// db.ExecContext（ctx`
// 从发票中删除
// 哪里
// 时间已创建<@结束
// 和TimeCreated>=@start；`，
// sql.Named（“开始”，开始时间），
// sql.Named（“end”，endTime），
// )
func Named(name string, value interface{}) NamedArg {
	// 此方法的存在是因为go1compat承诺
	// 不能保证结构不会增加更多字段，
	// 因此，未检查的结构文字是一个vet错误。因此，我们没有
	// 希望允许sql.NamedArg{name，value}。
	return NamedArg{Name: name, Value: value}
}

// IsolationLevel是TxOptions中使用的事务隔离级别。
type IsolationLevel int

// 驱动程序在BeginTx中可能支持的各种隔离级别。
// 如果驱动程序不支持给定的隔离级别，则可能会返回错误。
// None
// 请参阅https:
const (
	LevelDefault IsolationLevel = iota
	LevelReadUncommitted
	LevelReadCommitted
	LevelWriteCommitted
	LevelRepeatableRead
	LevelSnapshot
	LevelSerializable
	LevelLinearizable
)

// 字符串返回事务隔离级别的名称。
func (i IsolationLevel) String() string {
	switch i {
	case LevelDefault:
		return "Default"
	case LevelReadUncommitted:
		return "Read Uncommitted"
	case LevelReadCommitted:
		return "Read Committed"
	case LevelWriteCommitted:
		return "Write Committed"
	case LevelRepeatableRead:
		return "Repeatable Read"
	case LevelSnapshot:
		return "Snapshot"
	case LevelSerializable:
		return "Serializable"
	case LevelLinearizable:
		return "Linearizable"
	default:
		return "IsolationLevel(" + strconv.Itoa(int(i)) + ")"
	}
}

var _ fmt.Stringer = LevelDefault

// TxOptions保存要在DB.BeginTx中使用的事务选项。
type TxOptions struct {
	// 隔离是事务隔离级别。
	// 如果为零，则使用驱动程序或数据库的默认级别。
	Isolation IsolationLevel
	ReadOnly  bool
}

// RawBytes是一个字节片，它保存对所属内存的引用
// 数据库本身。扫描到RawBytes后，该片仅
// 在下次调用next、Scan或Close之前有效。
type RawBytes []byte

// NullString表示可能为null的字符串。
// NullString实现了Scanner接口，因此
// 它可用作扫描目标：
// None
// var s空字符串
// err:=db.QueryRow（“从foo中选择名称，其中id=？”，id）。扫描（&s）
// ...
// 如果s.有效{
// None
// }否则{
// None
// }
// None
type NullString struct {
	String string
	Valid  bool // 如果字符串不为NULL，则Valid为true
}

// Scan实现Scanner接口。
func (ns *NullString) Scan(value interface{}) error {
	if value == nil {
		ns.String, ns.Valid = "", false
		return nil
	}
	ns.Valid = true
	return convertAssign(&ns.String, value)
}

// 值实现驱动程序估价师接口。
func (ns NullString) Value() (driver.Value, error) {
	if !ns.Valid {
		return nil, nil
	}
	return ns.String, nil
}

// NullInt64表示可能为null的int64。
// NullInt64实现了Scanner接口，因此
// 它可以用作扫描目标，类似于NullString。
type NullInt64 struct {
	Int64 int64
	Valid bool // 如果Int64不为NULL，则Valid为true
}

// Scan实现Scanner接口。
func (n *NullInt64) Scan(value interface{}) error {
	if value == nil {
		n.Int64, n.Valid = 0, false
		return nil
	}
	n.Valid = true
	return convertAssign(&n.Int64, value)
}

// 值实现驱动程序估价师接口。
func (n NullInt64) Value() (driver.Value, error) {
	if !n.Valid {
		return nil, nil
	}
	return n.Int64, nil
}

// NullInt32表示可能为null的int32。
// NullInt32实现了Scanner接口，因此
// 它可以用作扫描目标，类似于NullString。
type NullInt32 struct {
	Int32 int32
	Valid bool // 如果Int32不为NULL，则Valid为true
}

// Scan实现Scanner接口。
func (n *NullInt32) Scan(value interface{}) error {
	if value == nil {
		n.Int32, n.Valid = 0, false
		return nil
	}
	n.Valid = true
	return convertAssign(&n.Int32, value)
}

// 值实现驱动程序估价师接口。
func (n NullInt32) Value() (driver.Value, error) {
	if !n.Valid {
		return nil, nil
	}
	return int64(n.Int32), nil
}

// NullInt16表示可能为null的int16。
// NullInt16实现了Scanner接口，因此
// 它可以用作扫描目标，类似于NullString。
type NullInt16 struct {
	Int16 int16
	Valid bool // 如果Int16不为NULL，则Valid为true
}

// Scan实现Scanner接口。
func (n *NullInt16) Scan(value interface{}) error {
	if value == nil {
		n.Int16, n.Valid = 0, false
		return nil
	}
	err := convertAssign(&n.Int16, value)
	n.Valid = err == nil
	return err
}

// 值实现驱动程序估价师接口。
func (n NullInt16) Value() (driver.Value, error) {
	if !n.Valid {
		return nil, nil
	}
	return int64(n.Int16), nil
}

// NullByte表示可能为null的字节。
// NullByte实现了Scanner接口，因此
// 它可以用作扫描目标，类似于NullString。
type NullByte struct {
	Byte  byte
	Valid bool // 如果字节不为NULL，则Valid为true
}

// Scan实现Scanner接口。
func (n *NullByte) Scan(value interface{}) error {
	if value == nil {
		n.Byte, n.Valid = 0, false
		return nil
	}
	err := convertAssign(&n.Byte, value)
	n.Valid = err == nil
	return err
}

// 值实现驱动程序估价师接口。
func (n NullByte) Value() (driver.Value, error) {
	if !n.Valid {
		return nil, nil
	}
	return int64(n.Byte), nil
}

// NullFloat64表示可能为null的float64。
// NullFloat64实现了Scanner接口，因此
// 它可以用作扫描目标，类似于NullString。
type NullFloat64 struct {
	Float64 float64
	Valid   bool // 如果Float64不为NULL，则Valid为true
}

// Scan实现Scanner接口。
func (n *NullFloat64) Scan(value interface{}) error {
	if value == nil {
		n.Float64, n.Valid = 0, false
		return nil
	}
	n.Valid = true
	return convertAssign(&n.Float64, value)
}

// 值实现驱动程序估价师接口。
func (n NullFloat64) Value() (driver.Value, error) {
	if !n.Valid {
		return nil, nil
	}
	return n.Float64, nil
}

// NullBool表示可能为null的bool。
// NullBool实现了Scanner接口，因此
// 它可以用作扫描目标，类似于NullString。
type NullBool struct {
	Bool  bool
	Valid bool // 如果Bool不为NULL，则Valid为true
}

// Scan实现Scanner接口。
func (n *NullBool) Scan(value interface{}) error {
	if value == nil {
		n.Bool, n.Valid = false, false
		return nil
	}
	n.Valid = true
	return convertAssign(&n.Bool, value)
}

// 值实现驱动程序估价师接口。
func (n NullBool) Value() (driver.Value, error) {
	if !n.Valid {
		return nil, nil
	}
	return n.Bool, nil
}

// NullTime表示时间。时间可以为null。
// NullTime实现了Scanner接口，因此
// 它可以用作扫描目标，类似于NullString。
type NullTime struct {
	Time  time.Time
	Valid bool // 如果时间不为NULL，则Valid为true
}

// Scan实现Scanner接口。
func (n *NullTime) Scan(value interface{}) error {
	if value == nil {
		n.Time, n.Valid = time.Time{}, false
		return nil
	}
	n.Valid = true
	return convertAssign(&n.Time, value)
}

// 值实现驱动程序估价师接口。
func (n NullTime) Value() (driver.Value, error) {
	if !n.Valid {
		return nil, nil
	}
	return n.Time, nil
}

// Scanner是Scan使用的接口。
type Scanner interface {
	// 扫描从数据库驱动程序分配一个值。
	// None
	// src值将属于以下类型之一：
	// None
	// int64
	// 浮动64
	// 布尔
	// []字节
	// 一串
	// 时间，时间
	// nil-表示空值
	// None
	// 如果无法存储该值，则应返回错误
	// 没有信息丢失。
	// None
	// 诸如[]字节之类的引用类型仅在下次调用Scan之前有效
	// 不应该保留。它们的底层内存由驱动程序拥有。
	// 如果需要保留，请在下次调用扫描之前复制它们的值。
	Scan(src interface{}) error
}

// Out可用于从存储过程检索输出值参数。
// None
// 并非所有驱动程序和数据库都支持输出值参数。
// None
// 用法示例：
// None
// 变量输出字符串
// _，err:=db.ExecContext（ctx，“ProcName”，sql.Named（“Arg1”，sql.Out{Dest:&outArg}））
type Out struct {
	_Named_Fields_Required struct{}

	// Dest是一个指针，指向将被设置为
	// 存储过程的输出参数。
	Dest interface{}

	// In是指参数是否为INOUT参数。如果是，则存储到
	// 过程是Dest指针的解引用值，然后替换为
	// 输出值。
	In bool
}

// 当QueryRow不返回
// 一行在这种情况下，QueryRow返回一个占位符*行值
// 将此错误延迟到扫描完成。
var ErrNoRows = errors.New("sql: no rows in result set")

// DB是一个数据库句柄，表示零个或多个数据池
// 潜在的联系。多个用户同时使用是安全的
// 戈罗季斯。
// None
// sql包自动创建和释放连接；信息技术
// 还维护空闲连接的空闲池。如果数据库有
// 每个连接状态的概念，可以可靠地观察到这种状态
// 在事务（Tx）或连接（Conn）内。一旦调用DB.Begin，则
// 返回的Tx绑定到单个连接。一旦犯下或
// 对事务调用回滚，该事务是
// 连接返回到DB的空闲连接池。游泳池的大小
// 可以使用SetMaxIdlecons进行控制。
type DB struct {
	// 仅限原子访问。位于结构顶部，以防止错误对齐
	// 在32位平台上。类型为time.Duration。
	waitDuration int64 // 等待新连接的总时间。

	connector driver.Connector
	// numClosed是一个原子计数器，表示
	// 闭合连接。Stmt.openStmt在清洁关闭前检查它
	// Stmt.css中的连接。
	numClosed uint64

	mu           sync.Mutex // 保护以下字段
	freeConn     []*driverConn
	connRequests map[uint64]chan connRequest
	nextRequest  uint64 // 在请求中使用的下一个键。
	numOpen      int    // 打开和挂起的打开连接数
	// 用于表示需要新连接
	// 运行connectionOpener（）的goroutine读取此文件并
	// 可能会在chan上发送OpenNewConnections（每个需要的连接发送一次）
	// 它在db.Close（）期间关闭。结束告诉连接打开者
	// goroutine要退出。
	openerCh          chan struct{}
	closed            bool
	dep               map[finalCloser]depSet
	lastPut           map[*driverConn]string // 最后一次看跌期权的跟踪；仅调试
	maxIdleCount      int                    // 零表示DefaultMaxIdlecons；否定意味着0
	maxOpen           int                    // <=0表示无限制
	maxLifetime       time.Duration          // 可重复使用连接的最长时间
	maxIdleTime       time.Duration          // 连接关闭前可能处于空闲状态的最长时间
	cleanerCh         chan struct{}
	waitCount         int64 // 等待的连接总数。
	maxIdleClosed     int64 // 由于空闲计数而关闭的连接总数。
	maxIdleTimeClosed int64 // 由于空闲时间而关闭的连接总数。
	maxLifetimeClosed int64 // 由于最大连接生存期限制而关闭的连接总数。

	stop func() // 停止取消连接开启器。
}

// ConnReuseStragey确定（*DB）。conn返回数据库连接的方式。
type connReuseStrategy uint8

const (
	// alwaysNewConn强制与数据库建立新连接。
	alwaysNewConn connReuseStrategy = iota
	// cachedOrNewConn返回缓存连接（如果可用），否则等待
	// 一个可用（如果已连接MaxOpenConns）或
	// 创建新的数据库连接。
	cachedOrNewConn
)

// driverConn使用互斥锁将driver.Conn包装到
// 在所有进入Conn的通话中（包括任何进入Conn的通话）
// 通过该Conn返回的接口，例如对Tx、Stmt、，
// 结果（行）
type driverConn struct {
	db        *DB
	createdAt time.Time

	sync.Mutex  // 卫兵跟随
	ci          driver.Conn
	needReset   bool // 如果为true，则应在使用前重置连接会话。
	closed      bool
	finalClosed bool // 已调用ci.Close
	openStmt    map[*driverStmt]bool

	// 由db.mu保护
	inUse      bool
	returnedAt time.Time // 创建或返回连接的时间。
	onPut      []func()  // 下一次返回conn时运行代码（保留db.mu）
	dbmuClosed bool      // 与closed相同，但由db.mu保护，用于removeClosedStmtLocked
}

func (dc *driverConn) releaseConn(err error) {
	dc.db.putConn(dc, err, true)
}

func (dc *driverConn) removeOpenStmt(ds *driverStmt) {
	dc.Lock()
	defer dc.Unlock()
	delete(dc.openStmt, ds)
}

func (dc *driverConn) expired(timeout time.Duration) bool {
	if timeout <= 0 {
		return false
	}
	return dc.createdAt.Add(timeout).Before(nowFunc())
}

// resetSession检查驱动程序连接是否需要
// 要重置的会话，如果需要，将其重置。
func (dc *driverConn) resetSession(ctx context.Context) error {
	dc.Lock()
	defer dc.Unlock()

	if !dc.needReset {
		return nil
	}
	if cr, ok := dc.ci.(driver.SessionResetter); ok {
		return cr.ResetSession(ctx)
	}
	return nil
}

// validateConnection检查连接是否有效并且可以
// 仍然可以使用。如果需要，它还会将会话标记为重置。
func (dc *driverConn) validateConnection(needsReset bool) bool {
	dc.Lock()
	defer dc.Unlock()

	if needsReset {
		dc.needReset = true
	}
	if cv, ok := dc.ci.(driver.Validator); ok {
		return cv.IsValid()
	}
	return true
}

// prepareLocked准备dc上的查询。当cg==nil时，dc必须跟踪
// 池中准备好的语句。
func (dc *driverConn) prepareLocked(ctx context.Context, cg stmtConnGrabber, query string) (*driverStmt, error) {
	si, err := ctxDriverPrepare(ctx, dc.ci, query)
	if err != nil {
		return nil, err
	}
	ds := &driverStmt{Locker: dc, si: si}

	// 如果只有一个连接抓取器，则无需管理打开的语句。
	if cg != nil {
		return ds, nil
	}

	// 跟踪每个driverConn的open语句，以便我们可以关闭它们
	// 在关闭控制室之前。
	// None
	// 包装所有驱动程序。Stmt为*driverStmt，以确保它们只关闭一次。
	if dc.openStmt == nil {
		dc.openStmt = make(map[*driverStmt]bool)
	}
	dc.openStmt[ds] = true
	return ds, nil
}

// db的互斥锁被保持。
func (dc *driverConn) closeDBLocked() func() error {
	dc.Lock()
	defer dc.Unlock()
	if dc.closed {
		return func() error { return errors.New("sql: duplicate driverConn close") }
	}
	dc.closed = true
	return dc.db.removeDepLocked(dc, dc)
}

func (dc *driverConn) Close() error {
	dc.Lock()
	if dc.closed {
		dc.Unlock()
		return errors.New("sql: duplicate driverConn close")
	}
	dc.closed = true
	dc.Unlock() // 不拖延；removeDep finalClose呼叫可能需要锁定

	// 现在更新需要持有dc.mu.Lock。
	dc.db.mu.Lock()
	dc.dbmuClosed = true
	fn := dc.db.removeDepLocked(dc, dc)
	dc.db.mu.Unlock()
	return fn()
}

func (dc *driverConn) finalClose() error {
	var err error

	// 每个*驱动器TMT都有一个dc锁。从dc中复制列表
	// 在每个stmt上调用close之前。
	var openStmt []*driverStmt
	withLock(dc, func() {
		openStmt = make([]*driverStmt, 0, len(dc.openStmt))
		for ds := range dc.openStmt {
			openStmt = append(openStmt, ds)
		}
		dc.openStmt = nil
	})
	for _, ds := range openStmt {
		ds.Close()
	}
	withLock(dc, func() {
		dc.finalClosed = true
		err = dc.ci.Close()
		dc.ci = nil
	})

	dc.db.mu.Lock()
	dc.db.numOpen--
	dc.db.maybeOpenNewConnections()
	dc.db.mu.Unlock()

	atomic.AddUint64(&dc.db.numClosed, 1)
	return err
}

// driverStmt将driver.Stmt与
// *它来自的driverConn，因此driverConn的锁可以
// 在通话中暂停。
type driverStmt struct {
	sync.Locker // 驾驶舱
	si          driver.Stmt
	closed      bool
	closeErr    error // 上一次关闭调用的返回值
}

// Close可确保driver.Stmt只关闭一次，并始终返回相同的结果
// 后果
func (ds *driverStmt) Close() error {
	ds.Lock()
	defer ds.Unlock()
	if ds.closed {
		return ds.closeErr
	}
	ds.closed = true
	ds.closeErr = ds.si.Close()
	return ds.closeErr
}

// depSet是最终失败者的优秀依赖项
type depSet map[interface{}]bool // 真布尔集

// finalCloser接口由（*DB）.addDep和相关
// 依赖引用计数。
type finalCloser interface {
	// 当对象的引用计数
	// 归零。（*DB）.mu在调用时未被保留。
	finalClose() error
}

// addDep注意到x现在依赖于dep，x的最终损失不会是
// 调用，直到使用removeDep删除x的所有依赖项。
func (db *DB) addDep(x finalCloser, dep interface{}) {
	db.mu.Lock()
	defer db.mu.Unlock()
	db.addDepLocked(x, dep)
}

func (db *DB) addDepLocked(x finalCloser, dep interface{}) {
	if db.dep == nil {
		db.dep = make(map[finalCloser]depSet)
	}
	xdep := db.dep[x]
	if xdep == nil {
		xdep = make(depSet)
		db.dep[x] = xdep
	}
	xdep[dep] = true
}

// removeDep注意到x不再依赖于dep。
// 如果x仍然有依赖项，则返回nil。
// 如果x不再具有任何依赖项，则其finalClose方法将为
// 调用并返回其错误值。
func (db *DB) removeDep(x finalCloser, dep interface{}) error {
	db.mu.Lock()
	fn := db.removeDepLocked(x, dep)
	db.mu.Unlock()
	return fn()
}

func (db *DB) removeDepLocked(x finalCloser, dep interface{}) func() error {

	xdep, ok := db.dep[x]
	if !ok {
		panic(fmt.Sprintf("unpaired removeDep: no deps for %T", x))
	}

	l0 := len(xdep)
	delete(xdep, dep)

	switch len(xdep) {
	case l0:
		// 什么也没拿走。不应该发生。
		panic(fmt.Sprintf("unpaired removeDep: no %T dep on %T", dep, x))
	case 0:
		// 没有更多的依赖项。
		delete(db.dep, x)
		return x.finalClose
	default:
		// 依赖关系仍然存在。
		return func() error { return nil }
	}
}

// 这是connectionOpener请求的大小（DB.openerCh）。
// 该值应大于最大典型值
// 用于db.maxOpen。如果maxOpen明显大于
// connectionRequestQueueSize则所有对*DB的调用都是可能的
// 阻止，直到connectionOpener能够满足积压的请求。
var connectionRequestQueueSize = 1000000

type dsnConnector struct {
	dsn    string
	driver driver.Driver
}

func (t dsnConnector) Connect(_ context.Context) (driver.Conn, error) {
	return t.driver.Open(t.dsn)
}

func (t dsnConnector) Driver() driver.Driver {
	return t.driver
}

// OpenDB使用连接器打开数据库，允许驱动程序
// 绕过基于字符串的数据源名称。
// None
// 大多数用户将通过特定于驱动程序的连接打开数据库
// 返回*DB的helper函数。不包括数据库驱动程序
// 在Go标准库中。请参阅https:
// 第三方驱动程序的列表。
// None
// OpenDB可能只是验证其参数，而不创建连接
// 到数据库。要验证数据源名称是否有效，请调用
// 发出砰的声响。
// None
// 返回的数据库对于多个goroutine并发使用是安全的
// 并维护自己的空闲连接池。因此，OpenDB
// 函数应该只调用一次。很少有必要这样做
// 关闭数据库。
func OpenDB(c driver.Connector) *DB {
	ctx, cancel := context.WithCancel(context.Background())
	db := &DB{
		connector:    c,
		openerCh:     make(chan struct{}, connectionRequestQueueSize),
		lastPut:      make(map[*driverConn]string),
		connRequests: make(map[uint64]chan connRequest),
		stop:         cancel,
	}

	go db.connectionOpener(ctx)

	return db
}

// 打开打开由其数据库驱动程序名称和
// 特定于驱动程序的数据源名称，通常至少包含一个
// 数据库名称和连接信息。
// None
// 大多数用户将通过特定于驱动程序的连接打开数据库
// 返回*DB的helper函数。不包括数据库驱动程序
// 在Go标准库中。请参阅https:
// 第三方驱动程序的列表。
// None
// Open可能只是验证其参数，而不创建连接
// 到数据库。要验证数据源名称是否有效，请调用
// 发出砰的声响。
// None
// 返回的数据库对于多个goroutine并发使用是安全的
// 并维护自己的空闲连接池。因此，开放
// 函数应该只调用一次。很少有必要这样做
// 关闭数据库。
func Open(driverName, dataSourceName string) (*DB, error) {
	driversMu.RLock()
	driveri, ok := drivers[driverName]
	driversMu.RUnlock()
	if !ok {
		return nil, fmt.Errorf("sql: unknown driver %q (forgotten import?)", driverName)
	}

	if driverCtx, ok := driveri.(driver.DriverContext); ok {
		connector, err := driverCtx.OpenConnector(dataSourceName)
		if err != nil {
			return nil, err
		}
		return OpenDB(connector), nil
	}

	return OpenDB(dsnConnector{dsn: dataSourceName, driver: driveri}), nil
}

func (db *DB) pingDC(ctx context.Context, dc *driverConn, release func(error)) error {
	var err error
	if pinger, ok := dc.ci.(driver.Pinger); ok {
		withLock(dc, func() {
			err = pinger.Ping(ctx)
		})
	}
	release(err)
	return err
}

// PingContext验证与数据库的连接是否仍处于活动状态，
// 如有必要，建立连接。
func (db *DB) PingContext(ctx context.Context) error {
	var dc *driverConn
	var err error

	for i := 0; i < maxBadConnRetries; i++ {
		dc, err = db.conn(ctx, cachedOrNewConn)
		if err != driver.ErrBadConn {
			break
		}
	}
	if err == driver.ErrBadConn {
		dc, err = db.conn(ctx, alwaysNewConn)
	}
	if err != nil {
		return err
	}

	return db.pingDC(ctx, dc, dc.releaseConn)
}

// Ping验证与数据库的连接是否仍处于活动状态，
// 如有必要，建立连接。
// None
// Ping在内部使用context.Background；要指定上下文，请使用
// PingContext。
func (db *DB) Ping() error {
	return db.PingContext(context.Background())
}

// 关闭关闭数据库并阻止启动新查询。
// Close然后等待服务器上已开始处理的所有查询
// 结束。
// None
// 关闭一个DB是很少见的，因为DB句柄本来就是要关闭的
// 长寿命，在许多戈罗廷之间共享。
func (db *DB) Close() error {
	db.mu.Lock()
	if db.closed { // 使DB.Close幂等元
		db.mu.Unlock()
		return nil
	}
	if db.cleanerCh != nil {
		close(db.cleanerCh)
	}
	var err error
	fns := make([]func() error, 0, len(db.freeConn))
	for _, dc := range db.freeConn {
		fns = append(fns, dc.closeDBLocked())
	}
	db.freeConn = nil
	db.closed = true
	for _, req := range db.connRequests {
		close(req)
	}
	db.mu.Unlock()
	for _, fn := range fns {
		err1 := fn()
		if err1 != nil {
			err = err1
		}
	}
	db.stop()
	if c, ok := db.connector.(io.Closer); ok {
		err1 := c.Close()
		if err1 != nil {
			err = err1
		}
	}
	return err
}

const defaultMaxIdleConns = 2

func (db *DB) maxIdleConnsLocked() int {
	n := db.maxIdleCount
	switch {
	case n == 0:
		// TODO（bradfitz）：询问驱动程序（如果支持）其默认首选项
		return defaultMaxIdleConns
	case n < 0:
		return 0
	default:
		return n
	}
}

func (db *DB) shortestIdleTimeLocked() time.Duration {
	if db.maxIdleTime <= 0 {
		return db.maxLifetime
	}
	if db.maxLifetime <= 0 {
		return db.maxIdleTime
	}

	min := db.maxIdleTime
	if min > db.maxLifetime {
		min = db.maxLifetime
	}
	return min
}

// SETMAXIDLECONS设置空闲模式中的最大连接数
// 连接池。
// None
// 如果MaxOpenConns大于0但小于新的MaxIdleConns，
// 然后，新的MaxIdleConns将减少，以匹配MaxOpenConns限制。
// None
// 如果n<=0，则不保留空闲连接。
// None
// 默认的最大空闲连接数当前为2。这可能会在未来发生变化
// 未来版本。
func (db *DB) SetMaxIdleConns(n int) {
	db.mu.Lock()
	if n > 0 {
		db.maxIdleCount = n
	} else {
		// 没有空闲连接。
		db.maxIdleCount = -1
	}
	// 确保maxIdle不超过maxOpen
	if db.maxOpen > 0 && db.maxIdleConnsLocked() > db.maxOpen {
		db.maxIdleCount = db.maxOpen
	}
	var closing []*driverConn
	idleCount := len(db.freeConn)
	maxIdle := db.maxIdleConnsLocked()
	if idleCount > maxIdle {
		closing = db.freeConn[maxIdle:]
		db.freeConn = db.freeConn[:maxIdle]
	}
	db.maxIdleClosed += int64(len(closing))
	db.mu.Unlock()
	for _, c := range closing {
		c.Close()
	}
}

// SetMaxOpenConns设置与数据库的最大打开连接数。
// None
// 如果MaxIdleConns大于0且新的MaxOpenConns小于
// maxidlecons，则会减少maxidlecons以匹配新的
// MaxOpenConns限制。
// None
// 如果n<=0，则对打开的连接数没有限制。
// 默认值为0（无限制）。
func (db *DB) SetMaxOpenConns(n int) {
	db.mu.Lock()
	db.maxOpen = n
	if n < 0 {
		db.maxOpen = 0
	}
	syncMaxIdle := db.maxOpen > 0 && db.maxIdleConnsLocked() > db.maxOpen
	db.mu.Unlock()
	if syncMaxIdle {
		db.SetMaxIdleConns(n)
	}
}

// SetConnMaxLifetime设置可重用连接的最长时间。
// None
// 在重新使用之前，过期的连接可能会被延迟关闭。
// None
// 如果d<=0，则连接不会由于连接的使用年限而关闭。
func (db *DB) SetConnMaxLifetime(d time.Duration) {
	if d < 0 {
		d = 0
	}
	db.mu.Lock()
	// 当生命周期缩短时醒来。
	if d > 0 && d < db.maxLifetime && db.cleanerCh != nil {
		select {
		case db.cleanerCh <- struct{}{}:
		default:
		}
	}
	db.maxLifetime = d
	db.startCleanerLocked()
	db.mu.Unlock()
}

// SetConnMaxIdleTime设置连接空闲的最长时间。
// None
// 在重新使用之前，过期的连接可能会被延迟关闭。
// None
// 如果d<=0，则连接不会由于连接的空闲时间而关闭。
func (db *DB) SetConnMaxIdleTime(d time.Duration) {
	if d < 0 {
		d = 0
	}
	db.mu.Lock()
	defer db.mu.Unlock()

	// 空闲时间缩短时唤醒清洁器。
	if d > 0 && d < db.maxIdleTime && db.cleanerCh != nil {
		select {
		case db.cleanerCh <- struct{}{}:
		default:
		}
	}
	db.maxIdleTime = d
	db.startCleanerLocked()
}

// startCleanerLocked可根据需要启动连接清洁器。
func (db *DB) startCleanerLocked() {
	if (db.maxLifetime > 0 || db.maxIdleTime > 0) && db.numOpen > 0 && db.cleanerCh == nil {
		db.cleanerCh = make(chan struct{}, 1)
		go db.connectionCleaner(db.shortestIdleTimeLocked())
	}
}

func (db *DB) connectionCleaner(d time.Duration) {
	const minInterval = time.Second

	if d < minInterval {
		d = minInterval
	}
	t := time.NewTimer(d)

	for {
		select {
		case <-t.C:
		case <-db.cleanerCh: // maxLifetime已更改或数据库已关闭。
		}

		db.mu.Lock()

		d = db.shortestIdleTimeLocked()
		if db.closed || db.numOpen == 0 || d <= 0 {
			db.cleanerCh = nil
			db.mu.Unlock()
			return
		}

		closing := db.connectionCleanerRunLocked()
		db.mu.Unlock()
		for _, c := range closing {
			c.Close()
		}

		if d < minInterval {
			d = minInterval
		}
		t.Reset(d)
	}
}

func (db *DB) connectionCleanerRunLocked() (closing []*driverConn) {
	if db.maxLifetime > 0 {
		expiredSince := nowFunc().Add(-db.maxLifetime)
		for i := 0; i < len(db.freeConn); i++ {
			c := db.freeConn[i]
			if c.createdAt.Before(expiredSince) {
				closing = append(closing, c)
				last := len(db.freeConn) - 1
				db.freeConn[i] = db.freeConn[last]
				db.freeConn[last] = nil
				db.freeConn = db.freeConn[:last]
				i--
			}
		}
		db.maxLifetimeClosed += int64(len(closing))
	}

	if db.maxIdleTime > 0 {
		expiredSince := nowFunc().Add(-db.maxIdleTime)
		var expiredCount int64
		for i := 0; i < len(db.freeConn); i++ {
			c := db.freeConn[i]
			if db.maxIdleTime > 0 && c.returnedAt.Before(expiredSince) {
				closing = append(closing, c)
				expiredCount++
				last := len(db.freeConn) - 1
				db.freeConn[i] = db.freeConn[last]
				db.freeConn[last] = nil
				db.freeConn = db.freeConn[:last]
				i--
			}
		}
		db.maxIdleTimeClosed += expiredCount
	}
	return
}

// DBStats包含数据库统计信息。
type DBStats struct {
	MaxOpenConnections int // 打开到数据库的最大连接数。

	// 池状态
	OpenConnections int // 正在使用和空闲的已建立连接数。
	InUse           int // 当前正在使用的连接数。
	Idle            int // 空闲连接数。

	// 计数器
	WaitCount         int64         // 等待的连接总数。
	WaitDuration      time.Duration // 等待新连接被阻止的总时间。
	MaxIdleClosed     int64         // 由于SetMaxIdleConns而关闭的连接总数。
	MaxIdleTimeClosed int64         // 由于SetConnMaxIdleTime而关闭的连接总数。
	MaxLifetimeClosed int64         // 由于SetConnMaxLifetime而关闭的连接总数。
}

// Stats返回数据库统计信息。
func (db *DB) Stats() DBStats {
	wait := atomic.LoadInt64(&db.waitDuration)

	db.mu.Lock()
	defer db.mu.Unlock()

	stats := DBStats{
		MaxOpenConnections: db.maxOpen,

		Idle:            len(db.freeConn),
		OpenConnections: db.numOpen,
		InUse:           db.numOpen - len(db.freeConn),

		WaitCount:         db.waitCount,
		WaitDuration:      time.Duration(wait),
		MaxIdleClosed:     db.maxIdleClosed,
		MaxIdleTimeClosed: db.maxIdleTimeClosed,
		MaxLifetimeClosed: db.maxLifetimeClosed,
	}
	return stats
}

// 假设db.mu已锁定。
// 如果存在连接请求，但尚未达到连接限制，
// 然后告诉connectionOpener打开新的连接。
func (db *DB) maybeOpenNewConnections() {
	numRequests := len(db.connRequests)
	if db.maxOpen > 0 {
		numCanOpen := db.maxOpen - db.numOpen
		if numRequests > numCanOpen {
			numRequests = numCanOpen
		}
	}
	for numRequests > 0 {
		db.numOpen++ // 乐观地
		numRequests--
		if db.closed {
			return
		}
		db.openerCh <- struct{}{}
	}
}

// 在单独的goroutine中运行，在请求时打开新连接。
func (db *DB) connectionOpener(ctx context.Context) {
	for {
		select {
		case <-ctx.Done():
			return
		case <-db.openerCh:
			db.openNewConnection(ctx)
		}
	}
}

// 打开一个新连接
func (db *DB) openNewConnection(ctx context.Context) {
	// 可能是OpenNewConnections在发送之前已经执行了db.numOpen++了
	// 关于db.openerCh。如果
	// 连接失败或在返回前已关闭。
	ci, err := db.connector.Connect(ctx)
	db.mu.Lock()
	defer db.mu.Unlock()
	if db.closed {
		if err == nil {
			ci.Close()
		}
		db.numOpen--
		return
	}
	if err != nil {
		db.numOpen--
		db.putConnDBLocked(nil, err)
		db.maybeOpenNewConnections()
		return
	}
	dc := &driverConn{
		db:         db,
		createdAt:  nowFunc(),
		returnedAt: nowFunc(),
		ci:         ci,
	}
	if db.putConnDBLocked(dc, err) {
		db.addDepLocked(dc, dc)
	} else {
		db.numOpen--
		ci.Close()
	}
}

// connRequest表示一个新连接的请求
// 当没有空闲连接可用时，DB.conn将创建
// 创建一个新的connRequest并将其放在db.connRequests列表中。
type connRequest struct {
	conn *driverConn
	err  error
}

var errDBClosed = errors.New("sql: database is closed")

// nextRequestKeyLocked返回下一个连接请求密钥。
// 假设nextRequest不会溢出。
func (db *DB) nextRequestKeyLocked() uint64 {
	next := db.nextRequest
	db.nextRequest++
	return next
}

// conn返回新打开或缓存的*driverConn。
func (db *DB) conn(ctx context.Context, strategy connReuseStrategy) (*driverConn, error) {
	db.mu.Lock()
	if db.closed {
		db.mu.Unlock()
		return nil, errDBClosed
	}
	// 检查上下文是否已过期。
	select {
	default:
	case <-ctx.Done():
		db.mu.Unlock()
		return nil, ctx.Err()
	}
	lifetime := db.maxLifetime

	// 如果可能，首选免费连接。
	numFree := len(db.freeConn)
	if strategy == cachedOrNewConn && numFree > 0 {
		conn := db.freeConn[0]
		copy(db.freeConn, db.freeConn[1:])
		db.freeConn = db.freeConn[:numFree-1]
		conn.inUse = true
		if conn.expired(lifetime) {
			db.maxLifetimeClosed++
			db.mu.Unlock()
			conn.Close()
			return nil, driver.ErrBadConn
		}
		db.mu.Unlock()

		// 如果需要，请重置会话。
		if err := conn.resetSession(ctx); err == driver.ErrBadConn {
			conn.Close()
			return nil, driver.ErrBadConn
		}

		return conn, nil
	}

	// 没有免费连接，或者我们被要求不要使用。如果我们没有
	// 允许打开更多连接、发出请求并等待。
	if db.maxOpen > 0 && db.numOpen >= db.maxOpen {
		// 将请求通道设置为CONNESS。它被缓冲，以便
		// ConnectionOpen在等待读取req时不阻塞。
		req := make(chan connRequest, 1)
		reqKey := db.nextRequestKeyLocked()
		db.connRequests[reqKey] = req
		db.waitCount++
		db.mu.Unlock()

		waitStart := nowFunc()

		// 超时与上下文的连接请求。
		select {
		case <-ctx.Done():
			// 删除连接请求并确保未发送任何值
			// 拆下后，请在其上单击。
			db.mu.Lock()
			delete(db.connRequests, reqKey)
			db.mu.Unlock()

			atomic.AddInt64(&db.waitDuration, int64(time.Since(waitStart)))

			select {
			default:
			case ret, ok := <-req:
				if ok && ret.conn != nil {
					db.putConn(ret.conn, ret.err, false)
				}
			}
			return nil, ctx.Err()
		case ret, ok := <-req:
			atomic.AddInt64(&db.waitDuration, int64(time.Since(waitStart)))

			if !ok {
				return nil, errDBClosed
			}
			// 仅在策略为cachedOrNewConns时检查连接是否过期。
			// 如果我们需要一个新的连接，只需重新使用连接，而无需查看
			// 到期时。如果已过期，则在放置时将对其进行检查
			// 返回连接池。
			// 这将优先为客户机提供有效连接，而不是确切的连接
			// 生命周期，无论如何，它可能在这一点之后完全过期。
			if strategy == cachedOrNewConn && ret.err == nil && ret.conn.expired(lifetime) {
				db.mu.Lock()
				db.maxLifetimeClosed++
				db.mu.Unlock()
				ret.conn.Close()
				return nil, driver.ErrBadConn
			}
			if ret.conn == nil {
				return nil, ret.err
			}

			// 如果需要，请重置会话。
			if err := ret.conn.resetSession(ctx); err == driver.ErrBadConn {
				ret.conn.Close()
				return nil, driver.ErrBadConn
			}
			return ret.conn, ret.err
		}
	}

	db.numOpen++ // 乐观地
	db.mu.Unlock()
	ci, err := db.connector.Connect(ctx)
	if err != nil {
		db.mu.Lock()
		db.numOpen-- // 对先前的乐观看法是正确的
		db.maybeOpenNewConnections()
		db.mu.Unlock()
		return nil, err
	}
	db.mu.Lock()
	dc := &driverConn{
		db:         db,
		createdAt:  nowFunc(),
		returnedAt: nowFunc(),
		ci:         ci,
		inUse:      true,
	}
	db.addDepLocked(dc, dc)
	db.mu.Unlock()
	return dc, nil
}

// PutconHook是一个用于测试的钩子。
var putConnHook func(*DB, *driverConn)

// NoteUnusedDrivers声明指出ds已不再使用，应
// 尽可能关闭（当c下一次不使用时），除非c
// 已经关门了。
func (db *DB) noteUnusedDriverStatement(c *driverConn, ds *driverStmt) {
	db.mu.Lock()
	defer db.mu.Unlock()
	if c.inUse {
		c.onPut = append(c.onPut, func() {
			ds.Close()
		})
	} else {
		c.Lock()
		fc := c.finalClosed
		c.Unlock()
		if !fc {
			ds.Close()
		}
	}
}

// debugGetPut确定getConn和putConn是否调用“堆栈跟踪”
// 返回更多详细的崩溃。
const debugGetPut = false

// putConn将连接添加到db的空闲池。
// err是此连接上发生的最后一个错误（可选）。
func (db *DB) putConn(dc *driverConn, err error, resetSession bool) {
	if err != driver.ErrBadConn {
		if !dc.validateConnection(resetSession) {
			err = driver.ErrBadConn
		}
	}
	db.mu.Lock()
	if !dc.inUse {
		db.mu.Unlock()
		if debugGetPut {
			fmt.Printf("putConn(%v) DUPLICATE was: %s\n\nPREVIOUS was: %s", dc, stack(), db.lastPut[dc])
		}
		panic("sql: connection returned that was never out")
	}

	if err != driver.ErrBadConn && dc.expired(db.maxLifetime) {
		db.maxLifetimeClosed++
		err = driver.ErrBadConn
	}
	if debugGetPut {
		db.lastPut[dc] = stack()
	}
	dc.inUse = false
	dc.returnedAt = nowFunc()

	for _, fn := range dc.onPut {
		fn()
	}
	dc.onPut = nil

	if err == driver.ErrBadConn {
		// 不要重复使用坏的连接。
		// 由于conn被认为是坏的，并且正在被丢弃，请对其进行处理
		// 就这样结束了。不要在这里减少未结数，最终将结束
		// 小心点。
		db.maybeOpenNewConnections()
		db.mu.Unlock()
		dc.Close()
		return
	}
	if putConnHook != nil {
		putConnHook(db, dc)
	}
	added := db.putConnDBLocked(dc, nil)
	db.mu.Unlock()

	if !added {
		dc.Close()
		return
	}
}

// 满足请求或将driverConn放入空闲池并返回true
// 或者返回false。
// PutConndBlock将满足connRequest（如果有），或者它将满足connRequest
// 如果err==nil且空闲，则将*driverConn返回到freeConn列表
// 不会超过连接限制。
// 如果出错！=nil，忽略dc的值。
// 如果err==nil，则dc不得等于nil。
// 如果connRequest已完成或*driverConn已放置在
// freeConn列表，则返回true，否则返回false。
func (db *DB) putConnDBLocked(dc *driverConn, err error) bool {
	if db.closed {
		return false
	}
	if db.maxOpen > 0 && db.numOpen > db.maxOpen {
		return false
	}
	if c := len(db.connRequests); c > 0 {
		var req chan connRequest
		var reqKey uint64
		for reqKey, req = range db.connRequests {
			break
		}
		delete(db.connRequests, reqKey) // 从挂起的请求中删除。
		if err == nil {
			dc.inUse = true
		}
		req <- connRequest{
			conn: dc,
			err:  err,
		}
		return true
	} else if err == nil && !db.closed {
		if db.maxIdleConnsLocked() > len(db.freeConn) {
			db.freeConn = append(db.freeConn, dc)
			db.startCleanerLocked()
			return true
		}
		db.maxIdleClosed++
	}
	return false
}

// maxBadConnRetries是驱动程序返回时的最大重试次数
// driver.ErrBadConn在强制新连接之前发出断开连接的信号
// 要打开的连接。
const maxBadConnRetries = 2

// PrepareContext为以后的查询或执行创建准备好的语句。
// 多个查询或执行可以从
// 返回语句。
// 调用方必须调用语句的Close方法
// 当不再需要该语句时。
// None
// 提供的上下文用于编写语句，而不是用于
// 语句的执行。
func (db *DB) PrepareContext(ctx context.Context, query string) (*Stmt, error) {
	var stmt *Stmt
	var err error
	for i := 0; i < maxBadConnRetries; i++ {
		stmt, err = db.prepare(ctx, query, cachedOrNewConn)
		if err != driver.ErrBadConn {
			break
		}
	}
	if err == driver.ErrBadConn {
		return db.prepare(ctx, query, alwaysNewConn)
	}
	return stmt, err
}

// Prepare为以后的查询或执行创建准备好的语句。
// 多个查询或执行可以从
// 返回语句。
// 调用方必须调用语句的Close方法
// 当不再需要该语句时。
// None
// 准备使用上下文。内部背景；要指定上下文，请使用
// 准备文本。
func (db *DB) Prepare(query string) (*Stmt, error) {
	return db.PrepareContext(context.Background(), query)
}

func (db *DB) prepare(ctx context.Context, query string, strategy connReuseStrategy) (*Stmt, error) {
	// TODO:检查db.driver是否支持可选的
	// 如果是，则调用该接口，
	// 否则我们会事先准备好声明
	// 连接，并执行此准备好的语句
	// 我们要么需要使用此连接（如果是免费的），要么
	// 获取新连接+重新准备+在该连接上执行。
	dc, err := db.conn(ctx, strategy)
	if err != nil {
		return nil, err
	}
	return db.prepareDC(ctx, dc, dc.releaseConn, nil, query)
}

// prepareDC准备对driverConn的查询，并在之前调用release
// 返回。当cg==nil时，表示使用了连接池，并且
// 当cg！=无仅使用单个驱动程序连接。
func (db *DB) prepareDC(ctx context.Context, dc *driverConn, release func(error), cg stmtConnGrabber, query string) (*Stmt, error) {
	var ds *driverStmt
	var err error
	defer func() {
		release(err)
	}()
	withLock(dc, func() {
		ds, err = dc.prepareLocked(ctx, cg, query)
	})
	if err != nil {
		return nil, err
	}
	stmt := &Stmt{
		db:    db,
		query: query,
		cg:    cg,
		cgds:  ds,
	}

	// 当cg==nil时，此语句需要跟踪各种
	// 准备连接并记录stmt依赖关系
	// DB。
	if cg == nil {
		stmt.css = []connStmt{{dc, ds}}
		stmt.lastNumClosed = atomic.LoadUint64(&db.numClosed)
		db.addDep(stmt, stmt)
	}
	return stmt, nil
}

// ExecContext执行查询而不返回任何行。
// 参数用于查询中的任何占位符参数。
func (db *DB) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error) {
	var res Result
	var err error
	for i := 0; i < maxBadConnRetries; i++ {
		res, err = db.exec(ctx, query, args, cachedOrNewConn)
		if err != driver.ErrBadConn {
			break
		}
	}
	if err == driver.ErrBadConn {
		return db.exec(ctx, query, args, alwaysNewConn)
	}
	return res, err
}

// Exec执行查询时不返回任何行。
// 参数用于查询中的任何占位符参数。
// None
// Exec在内部使用context.Background；要指定上下文，请使用
// 执行上下文。
func (db *DB) Exec(query string, args ...interface{}) (Result, error) {
	return db.ExecContext(context.Background(), query, args...)
}

func (db *DB) exec(ctx context.Context, query string, args []interface{}, strategy connReuseStrategy) (Result, error) {
	dc, err := db.conn(ctx, strategy)
	if err != nil {
		return nil, err
	}
	return db.execDC(ctx, dc, dc.releaseConn, query, args)
}

func (db *DB) execDC(ctx context.Context, dc *driverConn, release func(error), query string, args []interface{}) (res Result, err error) {
	defer func() {
		release(err)
	}()
	execerCtx, ok := dc.ci.(driver.ExecerContext)
	var execer driver.Execer
	if !ok {
		execer, ok = dc.ci.(driver.Execer)
	}
	if ok {
		var nvdargs []driver.NamedValue
		var resi driver.Result
		withLock(dc, func() {
			nvdargs, err = driverArgsConnLocked(dc.ci, nil, args)
			if err != nil {
				return
			}
			resi, err = ctxDriverExec(ctx, execerCtx, execer, query, nvdargs)
		})
		if err != driver.ErrSkip {
			if err != nil {
				return nil, err
			}
			return driverResult{dc, resi}, nil
		}
	}

	var si driver.Stmt
	withLock(dc, func() {
		si, err = ctxDriverPrepare(ctx, dc.ci, query)
	})
	if err != nil {
		return nil, err
	}
	ds := &driverStmt{Locker: dc, si: si}
	defer ds.Close()
	return resultFromStatement(ctx, dc.ci, ds, args...)
}

// QueryContext执行返回行的查询，通常是SELECT。
// 参数用于查询中的任何占位符参数。
func (db *DB) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error) {
	var rows *Rows
	var err error
	for i := 0; i < maxBadConnRetries; i++ {
		rows, err = db.query(ctx, query, args, cachedOrNewConn)
		if err != driver.ErrBadConn {
			break
		}
	}
	if err == driver.ErrBadConn {
		return db.query(ctx, query, args, alwaysNewConn)
	}
	return rows, err
}

// 查询执行返回行的查询，通常是SELECT。
// 参数用于查询中的任何占位符参数。
// None
// 查询在内部使用context.Background；要指定上下文，请使用
// 查询上下文。
func (db *DB) Query(query string, args ...interface{}) (*Rows, error) {
	return db.QueryContext(context.Background(), query, args...)
}

func (db *DB) query(ctx context.Context, query string, args []interface{}, strategy connReuseStrategy) (*Rows, error) {
	dc, err := db.conn(ctx, strategy)
	if err != nil {
		return nil, err
	}

	return db.queryDC(ctx, nil, dc, dc.releaseConn, query, args)
}

// queryDC在给定连接上执行查询。
// 通过releaseConn函数释放连接。
// ctx上下文来自查询方法，txctx上下文来自
// 可选事务上下文。
func (db *DB) queryDC(ctx, txctx context.Context, dc *driverConn, releaseConn func(error), query string, args []interface{}) (*Rows, error) {
	queryerCtx, ok := dc.ci.(driver.QueryerContext)
	var queryer driver.Queryer
	if !ok {
		queryer, ok = dc.ci.(driver.Queryer)
	}
	if ok {
		var nvdargs []driver.NamedValue
		var rowsi driver.Rows
		var err error
		withLock(dc, func() {
			nvdargs, err = driverArgsConnLocked(dc.ci, nil, args)
			if err != nil {
				return
			}
			rowsi, err = ctxDriverQuery(ctx, queryerCtx, queryer, query, nvdargs)
		})
		if err != driver.ErrSkip {
			if err != nil {
				releaseConn(err)
				return nil, err
			}
			// 注意：dc的所有权转移到*行，将被释放
			// 与releaseConn合作。
			rows := &Rows{
				dc:          dc,
				releaseConn: releaseConn,
				rowsi:       rowsi,
			}
			rows.initContextClose(ctx, txctx)
			return rows, nil
		}
	}

	var si driver.Stmt
	var err error
	withLock(dc, func() {
		si, err = ctxDriverPrepare(ctx, dc.ci, query)
	})
	if err != nil {
		releaseConn(err)
		return nil, err
	}

	ds := &driverStmt{Locker: dc, si: si}
	rowsi, err := rowsiFromStatement(ctx, dc.ci, ds, args...)
	if err != nil {
		ds.Close()
		releaseConn(err)
		return nil, err
	}

	// 注意：ci的所有权转移到*行，将被释放
	// 与releaseConn合作。
	rows := &Rows{
		dc:          dc,
		releaseConn: releaseConn,
		rowsi:       rowsi,
		closeStmt:   ds,
	}
	rows.initContextClose(ctx, txctx)
	return rows, nil
}

// QueryRowContext执行一个最多返回一行的查询。
// QueryRowContext始终返回非nil值。错误将推迟到
// 调用行的扫描方法。
// 如果查询未选择任何行，*行的扫描将返回ErrNoRows。
// 否则，*行的扫描将扫描第一个选定行并丢弃
// 其余的。
func (db *DB) QueryRowContext(ctx context.Context, query string, args ...interface{}) *Row {
	rows, err := db.QueryContext(ctx, query, args...)
	return &Row{rows: rows, err: err}
}

// QueryRow执行一个最多返回一行的查询。
// QueryRow始终返回非nil值。错误将推迟到
// 调用行的扫描方法。
// 如果查询未选择任何行，*行的扫描将返回ErrNoRows。
// 否则，*行的扫描将扫描第一个选定行并丢弃
// 其余的。
// None
// QueryRow在内部使用context.Background；要指定上下文，请使用
// 查询上下文。
func (db *DB) QueryRow(query string, args ...interface{}) *Row {
	return db.QueryRowContext(context.Background(), query, args...)
}

// BeginTx启动一个事务。
// None
// 在提交或回滚事务之前，将使用提供的上下文。
// 如果取消上下文，sql包将回滚
// 交易。Tx.Commit将返回一个错误，如果上下文提供给
// BeginTx被取消。
// None
// 提供的TxOptions是可选的，如果应使用默认值，则可能为零。
// 如果使用了驱动程序不支持的非默认隔离级别，
// 将返回一个错误。
func (db *DB) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error) {
	var tx *Tx
	var err error
	for i := 0; i < maxBadConnRetries; i++ {
		tx, err = db.begin(ctx, opts, cachedOrNewConn)
		if err != driver.ErrBadConn {
			break
		}
	}
	if err == driver.ErrBadConn {
		return db.begin(ctx, opts, alwaysNewConn)
	}
	return tx, err
}

// 开始开始一项事务。默认隔离级别取决于
// 司机。
// None
// Begin在内部使用context.Background；要指定上下文，请使用
// 贝金特斯。
func (db *DB) Begin() (*Tx, error) {
	return db.BeginTx(context.Background(), nil)
}

func (db *DB) begin(ctx context.Context, opts *TxOptions, strategy connReuseStrategy) (tx *Tx, err error) {
	dc, err := db.conn(ctx, strategy)
	if err != nil {
		return nil, err
	}
	return db.beginDC(ctx, dc, dc.releaseConn, opts)
}

// beginDC启动一个事务。提供的dc必须有效且随时可用。
func (db *DB) beginDC(ctx context.Context, dc *driverConn, release func(error), opts *TxOptions) (tx *Tx, err error) {
	var txi driver.Tx
	keepConnOnRollback := false
	withLock(dc, func() {
		_, hasSessionResetter := dc.ci.(driver.SessionResetter)
		_, hasConnectionValidator := dc.ci.(driver.Validator)
		keepConnOnRollback = hasSessionResetter && hasConnectionValidator
		txi, err = ctxDriverBegin(ctx, opts, dc.ci)
	})
	if err != nil {
		release(err)
		return nil, err
	}

	// 安排事务在取消上下文时回滚。
	// 将“完成”设置为“真”后，将调用Tx中的“取消”功能。
	ctx, cancel := context.WithCancel(ctx)
	tx = &Tx{
		db:                 db,
		dc:                 dc,
		releaseConn:        release,
		txi:                txi,
		cancel:             cancel,
		keepConnOnRollback: keepConnOnRollback,
		ctx:                ctx,
	}
	go tx.awaitDone()
	return tx, nil
}

// 驱动程序返回数据库的底层驱动程序。
func (db *DB) Driver() driver.Driver {
	return db.connector.Driver()
}

// 对连接执行的任何操作都会返回ErrConnDone
// 已返回到连接池的。
var ErrConnDone = errors.New("sql: connection is already closed")

// Conn通过打开新连接返回单个连接
// 或者从连接池返回现有连接。康恩威尔
// 阻塞，直到返回连接或取消ctx。
// 在同一Conn上运行的查询将在同一数据库会话中运行。
// None
// 每个Conn在被使用后必须返回到数据库池
// 给康涅狄格打电话。
func (db *DB) Conn(ctx context.Context) (*Conn, error) {
	var dc *driverConn
	var err error
	for i := 0; i < maxBadConnRetries; i++ {
		dc, err = db.conn(ctx, cachedOrNewConn)
		if err != driver.ErrBadConn {
			break
		}
	}
	if err == driver.ErrBadConn {
		dc, err = db.conn(ctx, alwaysNewConn)
	}
	if err != nil {
		return nil, err
	}

	conn := &Conn{
		db: db,
		dc: dc,
	}
	return conn, nil
}

type releaseConn func(error)

// Conn表示单个数据库连接，而不是数据库池
// 连接。更喜欢从数据库运行查询，除非有特定的
// 需要一个连续的单数据库连接。
// None
// Conn必须调用Close以返回到数据库池的连接
// 并且可以与正在运行的查询同时执行。
// None
// 在调用Close之后，在
// 连接失败，错误已完成。
type Conn struct {
	db *DB

	// closemu防止连接在连接时关闭
	// 是一个活动查询。它在查询期间被保存以供读取
	// 而且只在关门的时候。
	closemu sync.RWMutex

	// dc在关闭前一直为所有，此时
	// 它已返回到连接池。
	dc *driverConn

	// 关闭时，从0到1仅完成一次转换。
	// 一旦完成，所有操作都会失败，并显示ErrConnDone。
	// 检查值时对值使用原子操作。
	done int32
}

// grabConn采用上下文来实现stmtConnGrabber
// 但是没有使用上下文。
func (c *Conn) grabConn(context.Context) (*driverConn, releaseConn, error) {
	if atomic.LoadInt32(&c.done) != 0 {
		return nil, nil, ErrConnDone
	}
	c.closemu.RLock()
	return c.dc, c.closemuRUnlockCondReleaseConn, nil
}

// PingContext验证与数据库的连接是否仍处于活动状态。
func (c *Conn) PingContext(ctx context.Context) error {
	dc, release, err := c.grabConn(ctx)
	if err != nil {
		return err
	}
	return c.db.pingDC(ctx, dc, release)
}

// ExecContext执行查询而不返回任何行。
// 参数用于查询中的任何占位符参数。
func (c *Conn) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error) {
	dc, release, err := c.grabConn(ctx)
	if err != nil {
		return nil, err
	}
	return c.db.execDC(ctx, dc, release, query, args)
}

// QueryContext执行返回行的查询，通常是SELECT。
// 参数用于查询中的任何占位符参数。
func (c *Conn) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error) {
	dc, release, err := c.grabConn(ctx)
	if err != nil {
		return nil, err
	}
	return c.db.queryDC(ctx, nil, dc, release, query, args)
}

// QueryRowContext执行一个最多返回一行的查询。
// QueryRowContext始终返回非nil值。错误将推迟到
// 调用行的扫描方法。
// 如果查询未选择任何行，*行的扫描将返回ErrNoRows。
// 否则，*行的扫描将扫描第一个选定行并丢弃
// 其余的。
func (c *Conn) QueryRowContext(ctx context.Context, query string, args ...interface{}) *Row {
	rows, err := c.QueryContext(ctx, query, args...)
	return &Row{rows: rows, err: err}
}

// PrepareContext为以后的查询或执行创建准备好的语句。
// 多个查询或执行可以从
// 返回语句。
// 调用方必须调用语句的Close方法
// 当不再需要该语句时。
// None
// 提供的上下文用于编写语句，而不是用于
// 语句的执行。
func (c *Conn) PrepareContext(ctx context.Context, query string) (*Stmt, error) {
	dc, release, err := c.grabConn(ctx)
	if err != nil {
		return nil, err
	}
	return c.db.prepareDC(ctx, dc, release, c, query)
}

// Raw执行f以公开的基础驱动程序连接
// f的持续时间。不得在f之外使用driverConn。
// None
// 一旦f返回且err为零，Conn将继续可用
// 直到呼叫Conn.Close。
func (c *Conn) Raw(f func(driverConn interface{}) error) (err error) {
	var dc *driverConn
	var release releaseConn

	// grabConn使用上下文来实现stmtConnGrabber，但未使用上下文。
	dc, release, err = c.grabConn(nil)
	if err != nil {
		return
	}
	fPanic := true
	dc.Mutex.Lock()
	defer func() {
		dc.Mutex.Unlock()

		// 如果f恐慌，fPanic将保持为真。
		// 确保将错误传递给release，以便连接
		// 可能会被丢弃。
		if fPanic {
			err = driver.ErrBadConn
		}
		release(err)
	}()
	err = f(dc.ci)
	fPanic = false

	return
}

// BeginTx启动一个事务。
// None
// 在提交或回滚事务之前，将使用提供的上下文。
// 如果取消上下文，sql包将回滚
// 交易。Tx.Commit将返回一个错误，如果上下文提供给
// BeginTx被取消。
// None
// 提供的TxOptions是可选的，如果应使用默认值，则可能为零。
// 如果使用了驱动程序不支持的非默认隔离级别，
// 将返回一个错误。
func (c *Conn) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error) {
	dc, release, err := c.grabConn(ctx)
	if err != nil {
		return nil, err
	}
	return c.db.beginDC(ctx, dc, release, opts)
}

// CloseMurUnlockConditReleaseConn读取解除锁定closemu
// 因为sql操作是用dc完成的。
func (c *Conn) closemuRUnlockCondReleaseConn(err error) {
	c.closemu.RUnlock()
	if err == driver.ErrBadConn {
		c.close(err)
	}
}

func (c *Conn) txCtx() context.Context {
	return nil
}

func (c *Conn) close(err error) error {
	if !atomic.CompareAndSwapInt32(&c.done, 0, 1) {
		return ErrConnDone
	}

	// 锁定周围，释放驾驶员连接
	// 确保在执行此操作之前已停止所有查询。
	c.closemu.Lock()
	defer c.closemu.Unlock()

	c.dc.releaseConn(err)
	c.dc = nil
	c.db = nil
	return err
}

// 关闭将返回到连接池的连接。
// 关闭后的所有操作将返回ErrConnDone。
// Close可以安全地与其他操作同时调用，并且
// 阻塞，直到所有其他操作完成。首先，这可能是有用的
// 取消任何已使用的上下文，然后在之后直接调用close。
func (c *Conn) Close() error {
	return c.close(nil)
}

// Tx是一个正在进行的数据库事务。
// None
// 事务必须以Commit或Rollback调用结束。
// None
// 调用Commit或Rollback后，将执行
// 事务失败，返回ErrTxDone。
// None
// 通过调用为事务准备的语句
// 事务的Prepare或Stmt方法已关闭
// 通过调用提交或回滚。
type Tx struct {
	db *DB

	// closemu阻止事务在存在时关闭
	// 是一个活动查询。它在查询期间被保存以供读取
	// 而且只在关门的时候。
	closemu sync.RWMutex

	// dc在提交或回滚之前是独占的，此时
	// 它和普特康一起退了回来。
	dc  *driverConn
	txi driver.Tx

	// 一旦Tx关闭以释放，将调用releaseConn
	// 任何被扣留的司机都可以回到游泳池。
	releaseConn func(error)

	// 在提交时，仅完成一次从0到1的转换
	// 或者回滚。一旦完成，所有操作都会失败
	// 呃，是的。
	// 检查值时对值使用原子操作。
	done int32

	// 如果驱动程序知道，则keepConnOnRollback为true
	// 如何重置连接的会话，如果需要，如何放弃
	// 连接。
	keepConnOnRollback bool

	// 为此事务准备的所有STMT。这些将在会议结束后关闭
	// 事务已提交或回滚。
	stmts struct {
		sync.Mutex
		v []*Stmt
	}

	// 在完成从0到1的转换后调用cancel。
	cancel func()

	// ctx在事务的生命周期内有效。
	ctx context.Context
}

// 等待完成直到Tx中的上下文被取消并回滚
// 如果事务尚未完成，则返回该事务。
func (tx *Tx) awaitDone() {
	// 等待提交或滚动事务
	// 返回，或关闭关联的上下文。
	<-tx.ctx.Done()

	// 丢弃并关闭用于确保
	// 事务已关闭，资源已释放。这
	// 如果事务已经完成，则回滚不执行任何操作
	// 承诺或回退。
	// 如果连接知道，请不要放弃连接
	// 如何重置会话。
	discardConnection := !tx.keepConnOnRollback
	tx.rollback(discardConnection)
}

func (tx *Tx) isDone() bool {
	return atomic.LoadInt32(&tx.done) != 0
}

// 对事务执行的任何操作都会返回ErrTxDone
// 已经提交或回滚的。
var ErrTxDone = errors.New("sql: transaction has already been committed or rolled back")

// close返回到池的连接，并
// 必须仅由Tx.rollback或Tx.Commit调用，而
// tx已被取消，不会同时执行。
func (tx *Tx) close(err error) {
	tx.releaseConn(err)
	tx.dc = nil
	tx.txi = nil
}

// hookTxGrabConn指定要调用的可选钩子
// 成功呼叫（*Tx）.grabConn。用于测试。
var hookTxGrabConn func()

func (tx *Tx) grabConn(ctx context.Context) (*driverConn, releaseConn, error) {
	select {
	default:
	case <-ctx.Done():
		return nil, nil, ctx.Err()
	}

	// closemu.RLock必须在检查isDone之前出现，以防止发送失败
	// 在执行查询时关闭。
	tx.closemu.RLock()
	if tx.isDone() {
		tx.closemu.RUnlock()
		return nil, nil, ErrTxDone
	}
	if hookTxGrabConn != nil { // 试验钩
		hookTxGrabConn()
	}
	return tx.dc, tx.closemuRUnlockRelease, nil
}

func (tx *Tx) txCtx() context.Context {
	return tx.ctx
}

// closemuRUnlockRelease用作中的func（错误）方法值
// ExecContext和QueryContext。解锁释放控制按钮可保持
// 驱动程序连接从返回到连接池，直到
// 行已关闭。
func (tx *Tx) closemuRUnlockRelease(error) {
	tx.closemu.RUnlock()
}

// 关闭为此事务准备的所有STMT。
func (tx *Tx) closePrepared() {
	tx.stmts.Lock()
	defer tx.stmts.Unlock()
	for _, stmt := range tx.stmts.v {
		stmt.Close()
	}
}

// 提交提交事务。
func (tx *Tx) Commit() error {
	// 首先检查上下文以避免事务泄漏。
	// 如果将其放在tx.done CompareAndSwap语句后面，我们无法确保
	// tx.done与实际提交操作之间的一致性。
	select {
	default:
	case <-tx.ctx.Done():
		if atomic.LoadInt32(&tx.done) == 1 {
			return ErrTxDone
		}
		return tx.ctx.Err()
	}
	if !atomic.CompareAndSwapInt32(&tx.done, 0, 1) {
		return ErrTxDone
	}

	// 取消发送以释放任何激活的R-closemu锁。
	// 这样做是安全的，因为tx.done已经转换
	// 从0到1。在回滚之前保持W-closemu锁
	// 以确保没有其他连接具有活动查询。
	tx.cancel()
	tx.closemu.Lock()
	tx.closemu.Unlock()

	var err error
	withLock(tx.dc, func() {
		err = tx.txi.Commit()
	})
	if err != driver.ErrBadConn {
		tx.closePrepared()
	}
	tx.close(err)
	return err
}

var rollbackHook func()

// 回滚中止事务，并可以选择强制池放弃
// 连接。
func (tx *Tx) rollback(discardConn bool) error {
	if !atomic.CompareAndSwapInt32(&tx.done, 0, 1) {
		return ErrTxDone
	}

	if rollbackHook != nil {
		rollbackHook()
	}

	// 取消发送以释放任何激活的R-closemu锁。
	// 这样做是安全的，因为tx.done已经转换
	// 从0到1。在回滚之前保持W-closemu锁
	// 以确保没有其他连接具有活动查询。
	tx.cancel()
	tx.closemu.Lock()
	tx.closemu.Unlock()

	var err error
	withLock(tx.dc, func() {
		err = tx.txi.Rollback()
	})
	if err != driver.ErrBadConn {
		tx.closePrepared()
	}
	if discardConn {
		err = driver.ErrBadConn
	}
	tx.close(err)
	return err
}

// 回滚中止事务。
func (tx *Tx) Rollback() error {
	return tx.rollback(false)
}

// PrepareContext创建一个准备好的语句，供在事务中使用。
// None
// 返回的语句在事务中运行，并将被关闭
// 当事务已提交或回滚时。
// None
// 要在此事务上使用现有的已准备语句，请参阅Tx.Stmt。
// None
// 提供的上下文将用于准备上下文，而不是
// 用于执行返回的语句。返回的语句
// 将在事务上下文中运行。
func (tx *Tx) PrepareContext(ctx context.Context, query string) (*Stmt, error) {
	dc, release, err := tx.grabConn(ctx)
	if err != nil {
		return nil, err
	}

	stmt, err := tx.db.prepareDC(ctx, dc, release, tx, query)
	if err != nil {
		return nil, err
	}
	tx.stmts.Lock()
	tx.stmts.v = append(tx.stmts.v, stmt)
	tx.stmts.Unlock()
	return stmt, nil
}

// Prepare创建一条准备好的语句，以便在事务中使用。
// None
// 返回的语句在事务中运行，不能再执行
// 一旦事务被提交或回滚，就可以使用。
// None
// 要在此事务上使用现有的已准备语句，请参阅Tx.Stmt。
// None
// 准备使用上下文。内部背景；要指定上下文，请使用
// 准备文本。
func (tx *Tx) Prepare(query string) (*Stmt, error) {
	return tx.PrepareContext(context.Background(), query)
}

// StmtContext从返回特定于事务的准备语句
// 现有声明。
// None
// 例子：
// updateMoney，err:=db.Prepare（“更新余额集money=money+？其中id=？”）
// ...
// tx，err:=db.Begin（）
// ...
// res，err:=tx.StmtContext（ctx，updateMoney）.Exec（123.4598293203）
// None
// 提供的上下文用于编写语句，而不是用于
// 语句的执行。
// None
// 返回的语句在事务中运行，并将被关闭
// 当事务已提交或回滚时。
func (tx *Tx) StmtContext(ctx context.Context, stmt *Stmt) *Stmt {
	dc, release, err := tx.grabConn(ctx)
	if err != nil {
		return &Stmt{stickyErr: err}
	}
	defer release(nil)

	if tx.db != stmt.db {
		return &Stmt{stickyErr: errors.New("sql: Tx.Stmt: statement from different database used")}
	}
	var si driver.Stmt
	var parentStmt *Stmt
	stmt.mu.Lock()
	if stmt.closed || stmt.cg != nil {
		// 如果语句已关闭或已属于
		// 事务，我们无法在此连接中重用它。
		// 因为tx.StmtContext不需要使用
		// Stmt已经属于tx，我们忽略此边缘情况并
		// 在这种情况下，重新准备陈述。无需添加
		// 这方面的代码复杂性。
		stmt.mu.Unlock()
		withLock(dc, func() {
			si, err = ctxDriverPrepare(ctx, dc.ci, stmt.query)
		})
		if err != nil {
			return &Stmt{stickyErr: err}
		}
	} else {
		stmt.removeClosedStmtLocked()
		// 看看是否已经准备好了关于这个连接的声明，
		// 如果可能的话，重新使用它。
		for _, v := range stmt.css {
			if v.dc == dc {
				si = v.ds.si
				break
			}
		}

		stmt.mu.Unlock()

		if si == nil {
			var ds *driverStmt
			withLock(dc, func() {
				ds, err = stmt.prepareOnConnLocked(ctx, dc)
			})
			if err != nil {
				return &Stmt{stickyErr: err}
			}
			si = ds.si
		}
		parentStmt = stmt
	}

	txs := &Stmt{
		db: tx.db,
		cg: tx,
		cgds: &driverStmt{
			Locker: dc,
			si:     si,
		},
		parentStmt: parentStmt,
		query:      stmt.query,
	}
	if parentStmt != nil {
		tx.db.addDep(parentStmt, txs)
	}
	tx.stmts.Lock()
	tx.stmts.v = append(tx.stmts.v, txs)
	tx.stmts.Unlock()
	return txs
}

// Stmt从中返回特定于事务的准备语句
// 现有声明。
// None
// 例子：
// updateMoney，err:=db.Prepare（“更新余额集money=money+？其中id=？”）
// ...
// tx，err:=db.Begin（）
// ...
// res，err:=tx.Stmt（updateMoney）.Exec（123.4598293203）
// None
// 返回的语句在事务中运行，并将被关闭
// 当事务已提交或回滚时。
// None
// Stmt在内部使用context.Background；要指定上下文，请使用
// StmtContext。
func (tx *Tx) Stmt(stmt *Stmt) *Stmt {
	return tx.StmtContext(context.Background(), stmt)
}

// ExecContext执行不返回行的查询。
// 例如：插入和更新。
func (tx *Tx) ExecContext(ctx context.Context, query string, args ...interface{}) (Result, error) {
	dc, release, err := tx.grabConn(ctx)
	if err != nil {
		return nil, err
	}
	return tx.db.execDC(ctx, dc, release, query, args)
}

// Exec执行不返回行的查询。
// 例如：插入和更新。
// None
// Exec在内部使用context.Background；要指定上下文，请使用
// 执行上下文。
func (tx *Tx) Exec(query string, args ...interface{}) (Result, error) {
	return tx.ExecContext(context.Background(), query, args...)
}

// QueryContext执行返回行的查询，通常是SELECT。
func (tx *Tx) QueryContext(ctx context.Context, query string, args ...interface{}) (*Rows, error) {
	dc, release, err := tx.grabConn(ctx)
	if err != nil {
		return nil, err
	}

	return tx.db.queryDC(ctx, tx.ctx, dc, release, query, args)
}

// 查询执行返回行的查询，通常是SELECT。
// None
// 查询在内部使用context.Background；要指定上下文，请使用
// 查询上下文。
func (tx *Tx) Query(query string, args ...interface{}) (*Rows, error) {
	return tx.QueryContext(context.Background(), query, args...)
}

// QueryRowContext执行一个最多返回一行的查询。
// QueryRowContext始终返回非nil值。错误将推迟到
// 调用行的扫描方法。
// 如果查询未选择任何行，*行的扫描将返回ErrNoRows。
// 否则，*行的扫描将扫描第一个选定行并丢弃
// 其余的。
func (tx *Tx) QueryRowContext(ctx context.Context, query string, args ...interface{}) *Row {
	rows, err := tx.QueryContext(ctx, query, args...)
	return &Row{rows: rows, err: err}
}

// QueryRow执行一个最多返回一行的查询。
// QueryRow始终返回非nil值。错误将推迟到
// 调用行的扫描方法。
// 如果查询未选择任何行，*行的扫描将返回ErrNoRows。
// 否则，*行的扫描将扫描第一个选定行并丢弃
// 其余的。
// None
// QueryRow在内部使用context.Background；要指定上下文，请使用
// 查询上下文。
func (tx *Tx) QueryRow(query string, args ...interface{}) *Row {
	return tx.QueryRowContext(context.Background(), query, args...)
}

// connStmt是一个针对特定连接的准备好的语句。
type connStmt struct {
	dc *driverConn
	ds *driverStmt
}

// stmtConnGrabber表示将返回基础数据的Tx或Conn
// 驱动开关和释放功能。
type stmtConnGrabber interface {
	// grabConn返回driverConn和相关的释放函数
	// 操作完成时必须调用。
	grabConn(context.Context) (*driverConn, releaseConn, error)

	// txCtx返回事务上下文（如果可用）。
	// 返回的上下文应与一起选择
	// 等待取消时的任何查询上下文。
	txCtx() context.Context
}

var (
	_ stmtConnGrabber = &Tx{}
	_ stmtConnGrabber = &Conn{}
)

// Stmt是一个预先准备好的语句。
// Stmt对于多个goroutine并发使用是安全的。
// None
// 如果在Tx或Conn上准备Stmt，它将绑定到单个
// 永远的潜在联系。如果Tx或Conn关闭，Stmt将
// 变得不可用，所有操作都将返回错误。
// 如果在DB上准备了Stmt，则它将在数据库的生命周期内保持可用
// DB。当Stmt需要在新的基础连接上执行时，它将
// 自动准备新连接。
type Stmt struct {
	// 不变的：
	db        *DB    // 我们从哪里来
	query     string // 创建了Stmt
	stickyErr error  // 如果非nil，则为所有操作返回此错误

	closemu sync.RWMutex // 仅在关闭期间保持，否则读取。

	// 如果Stmt是在Tx或Conn上准备的，则cg存在并将
	// 只能从cg获取连接。
	// 如果cg为零，则Stmt必须获取任意连接
	// 并确定是否必须通过以下方式再次准备stmt：
	// 检查css。
	cg   stmtConnGrabber
	cgds *driverStmt

	// 当事务特定语句
	// 是从同一天准备的相同声明中请求的
	// conn.parentStmt用于跟踪此语句的依赖项
	// 在其原始（“父”）声明上，以便parentStmt可以
	// 由用户关闭，而无需用户知道是否
	// 任何事务仍在使用它。
	parentStmt *Stmt

	mu     sync.Mutex // 保护其余的字段
	closed bool

	// css是底层驱动程序语句接口的列表
	// 在特定连接上有效的。这只是
	// 如果cg==nil且发现一个具有空闲状态，则使用此选项
	// 连接。如果cg！=无，始终使用cgds。
	css []connStmt

	// lastNumClosed是在创建Stmt时从db.numClosed复制的
	// 没有tx和css中关闭的连接将被删除。
	lastNumClosed uint64
}

// ExecContext使用给定的参数和
// 返回总结语句效果的结果。
func (s *Stmt) ExecContext(ctx context.Context, args ...interface{}) (Result, error) {
	s.closemu.RLock()
	defer s.closemu.RUnlock()

	var res Result
	strategy := cachedOrNewConn
	for i := 0; i < maxBadConnRetries+1; i++ {
		if i == maxBadConnRetries {
			strategy = alwaysNewConn
		}
		dc, releaseConn, ds, err := s.connStmt(ctx, strategy)
		if err != nil {
			if err == driver.ErrBadConn {
				continue
			}
			return nil, err
		}

		res, err = resultFromStatement(ctx, dc.ci, ds, args...)
		releaseConn(err)
		if err != driver.ErrBadConn {
			return res, err
		}
	}
	return nil, driver.ErrBadConn
}

// Exec使用给定的参数和参数执行准备好的语句
// 返回总结语句效果的结果。
// None
// Exec在内部使用context.Background；要指定上下文，请使用
// 执行上下文。
func (s *Stmt) Exec(args ...interface{}) (Result, error) {
	return s.ExecContext(context.Background(), args...)
}

func resultFromStatement(ctx context.Context, ci driver.Conn, ds *driverStmt, args ...interface{}) (Result, error) {
	ds.Lock()
	defer ds.Unlock()

	dargs, err := driverArgsConnLocked(ci, ds, args)
	if err != nil {
		return nil, err
	}

	resi, err := ctxDriverStmtExec(ctx, ds.si, dargs)
	if err != nil {
		return nil, err
	}
	return driverResult{ds.Locker, resi}, nil
}

// removeClosedStmtLocked删除s.css中的闭合连接。
// None
// 为了避免DB.mu上的锁争用，我们只在
// s、 db.numClosed-s.lastNum足够大。
func (s *Stmt) removeClosedStmtLocked() {
	t := len(s.css)/2 + 1
	if t > 10 {
		t = 10
	}
	dbClosed := atomic.LoadUint64(&s.db.numClosed)
	if dbClosed-s.lastNumClosed < uint64(t) {
		return
	}

	s.db.mu.Lock()
	for i := 0; i < len(s.css); i++ {
		if s.css[i].dc.dbmuClosed {
			s.css[i] = s.css[len(s.css)-1]
			s.css = s.css[:len(s.css)-1]
			i--
		}
	}
	s.db.mu.Unlock()
	s.lastNumClosed = dbClosed
}

// connStmt返回要在其上执行
// 语句、用于调用以释放连接的函数以及
// 绑定到该连接的语句。
func (s *Stmt) connStmt(ctx context.Context, strategy connReuseStrategy) (dc *driverConn, releaseConn func(error), ds *driverStmt, err error) {
	if err = s.stickyErr; err != nil {
		return
	}
	s.mu.Lock()
	if s.closed {
		s.mu.Unlock()
		err = errors.New("sql: statement is closed")
		return
	}

	// 在事务或连接中，我们总是使用
	// stmt是在上创建的。
	if s.cg != nil {
		s.mu.Unlock()
		dc, releaseConn, err = s.cg.grabConn(ctx) // 阻塞，等待连接。
		if err != nil {
			return
		}
		return dc, releaseConn, s.cgds, nil
	}

	s.removeClosedStmtLocked()
	s.mu.Unlock()

	dc, err = s.db.conn(ctx, strategy)
	if err != nil {
		return nil, nil, nil, err
	}

	s.mu.Lock()
	for _, v := range s.css {
		if v.dc == dc {
			s.mu.Unlock()
			return dc, dc.releaseConn, v.ds, nil
		}
	}
	s.mu.Unlock()

	// 没有运气；我们需要准备有关这方面的声明
	withLock(dc, func() {
		ds, err = s.prepareOnConnLocked(ctx, dc)
	})
	if err != nil {
		dc.releaseConn(err)
		return nil, nil, nil, err
	}

	return dc, dc.releaseConn, ds, nil
}

// PrepareonConLocked在dc上的Stmt s中准备查询，并将其添加到
// 在语句上打开connStmt。它假定调用方持有dc上的锁。
func (s *Stmt) prepareOnConnLocked(ctx context.Context, dc *driverConn) (*driverStmt, error) {
	si, err := dc.prepareLocked(ctx, s.cg, s.query)
	if err != nil {
		return nil, err
	}
	cs := connStmt{dc, si}
	s.mu.Lock()
	s.css = append(s.css, cs)
	s.mu.Unlock()
	return cs.ds, nil
}

// QueryContext使用给定的参数执行准备好的查询语句
// 并以*行的形式返回查询结果。
func (s *Stmt) QueryContext(ctx context.Context, args ...interface{}) (*Rows, error) {
	s.closemu.RLock()
	defer s.closemu.RUnlock()

	var rowsi driver.Rows
	strategy := cachedOrNewConn
	for i := 0; i < maxBadConnRetries+1; i++ {
		if i == maxBadConnRetries {
			strategy = alwaysNewConn
		}
		dc, releaseConn, ds, err := s.connStmt(ctx, strategy)
		if err != nil {
			if err == driver.ErrBadConn {
				continue
			}
			return nil, err
		}

		rowsi, err = rowsiFromStatement(ctx, dc.ci, ds, args...)
		if err == nil {
			// 注意：ci的所有权转移到*行，将被释放
			// 与releaseConn合作。
			rows := &Rows{
				dc:    dc,
				rowsi: rowsi,
				// 释放控制设置如下
			}
			// 必须在initContextClose之前添加addDep，否则它可能会尝试
			// 在添加之前删除。
			s.db.addDep(s, rows)

			// 必须在initContextClose之前设置releaseConn，否则可能会
			// 在设置连接之前释放连接。
			rows.releaseConn = func(err error) {
				releaseConn(err)
				s.db.removeDep(s, rows)
			}
			var txctx context.Context
			if s.cg != nil {
				txctx = s.cg.txCtx()
			}
			rows.initContextClose(ctx, txctx)
			return rows, nil
		}

		releaseConn(err)
		if err != driver.ErrBadConn {
			return nil, err
		}
	}
	return nil, driver.ErrBadConn
}

// 查询使用给定的参数执行准备好的查询语句
// 并以*行的形式返回查询结果。
// None
// 查询在内部使用context.Background；要指定上下文，请使用
// 查询上下文。
func (s *Stmt) Query(args ...interface{}) (*Rows, error) {
	return s.QueryContext(context.Background(), args...)
}

func rowsiFromStatement(ctx context.Context, ci driver.Conn, ds *driverStmt, args ...interface{}) (driver.Rows, error) {
	ds.Lock()
	defer ds.Unlock()
	dargs, err := driverArgsConnLocked(ci, ds, args)
	if err != nil {
		return nil, err
	}
	return ctxDriverStmtQuery(ctx, ds.si, dargs)
}

// QueryRowContext使用给定的参数执行准备好的查询语句。
// 如果在语句执行期间发生错误，则该错误将被删除
// 通过调用对返回的*行进行扫描返回，该行始终为非nil。
// 如果查询未选择任何行，*行的扫描将返回ErrNoRows。
// 否则，*行的扫描将扫描第一个选定行并丢弃
// 其余的。
func (s *Stmt) QueryRowContext(ctx context.Context, args ...interface{}) *Row {
	rows, err := s.QueryContext(ctx, args...)
	if err != nil {
		return &Row{err: err}
	}
	return &Row{rows: rows}
}

// QueryRow使用给定的参数执行准备好的查询语句。
// 如果在语句执行期间发生错误，则该错误将被删除
// 通过调用对返回的*行进行扫描返回，该行始终为非nil。
// 如果查询未选择任何行，*行的扫描将返回ErrNoRows。
// 否则，*行的扫描将扫描第一个选定行并丢弃
// 其余的。
// None
// 用法示例：
// None
// 变量名称字符串
// 错误：=nameByUseridStmt.QueryRow（id）.Scan（&name）
// None
// QueryRow在内部使用context.Background；要指定上下文，请使用
// 查询上下文。
func (s *Stmt) QueryRow(args ...interface{}) *Row {
	return s.QueryRowContext(context.Background(), args...)
}

// 关闭语句。
func (s *Stmt) Close() error {
	s.closemu.Lock()
	defer s.closemu.Unlock()

	if s.stickyErr != nil {
		return s.stickyErr
	}
	s.mu.Lock()
	if s.closed {
		s.mu.Unlock()
		return nil
	}
	s.closed = true
	txds := s.cgds
	s.cgds = nil

	s.mu.Unlock()

	if s.cg == nil {
		return s.db.removeDep(s, s)
	}

	if s.parentStmt != nil {
		// 如果设置了parentStmt，则不能关闭s.txds，因为它已存储
		// 在parentStmt的css数组中。
		return s.db.removeDep(s.parentStmt, s)
	}
	return txds.Close()
}

func (s *Stmt) finalClose() error {
	s.mu.Lock()
	defer s.mu.Unlock()
	if s.css != nil {
		for _, v := range s.css {
			s.db.noteUnusedDriverStatement(v.dc, v.ds)
			v.dc.removeOpenStmt(v.ds)
		}
		s.css = nil
	}
	return nil
}

// 行是查询的结果。其光标在第一行之前开始
// 结果集的一部分。使用“下一步”从一行前进到另一行。
type Rows struct {
	dc          *driverConn // 拥有；关闭时必须调用releaseConn才能释放
	releaseConn func(error)
	rowsi       driver.Rows
	cancel      func()      // 行关闭时调用，可能为零。
	closeStmt   *driverStmt // 如果非nil，则在关闭时关闭语句

	// closemu防止行在存在时关闭
	// 是一个活动的流式处理结果。在非关闭操作期间，它会被保存以供读取
	// 而且只在关门的时候。
	// None
	// closemu保护lasterr并关闭。
	closemu sync.RWMutex
	closed  bool
	lasterr error // 仅当closed为true时才为非nil

	// lastcols仅用于Scan、Next和NextResultSet中，这是预期的
	// 不得同时召开。
	lastcols []driver.Value
}

// LastErrorErrorLocked返回LastError或提供的错误。
// rs.closemu必须被读锁定。
func (rs *Rows) lasterrOrErrLocked(err error) error {
	if rs.lasterr != nil && rs.lasterr != io.EOF {
		return rs.lasterr
	}
	return err
}

// bypassRowsAwaitDone仅用于测试。
// 如果为true，则不会从上下文自动关闭行。
var bypassRowsAwaitDone = false

func (rs *Rows) initContextClose(ctx, txctx context.Context) {
	if ctx.Done() == nil && (txctx == nil || txctx.Done() == nil) {
		return
	}
	if bypassRowsAwaitDone {
		return
	}
	ctx, rs.cancel = context.WithCancel(ctx)
	go rs.awaitDone(ctx, txctx)
}

// 等待完成，直到ctx或txctx被取消。提供ctx
// 并在查询行关闭时取消。
// 如果查询是在事务中发出的，则事务的上下文
// txctx中也提供了，以确保在Tx关闭时关闭行。
func (rs *Rows) awaitDone(ctx, txctx context.Context) {
	var txctxDone <-chan struct{}
	if txctx != nil {
		txctxDone = txctx.Done()
	}
	select {
	case <-ctx.Done():
	case <-txctxDone:
	}
	rs.close(ctx.Err())
}

// 下一步准备下一个结果行，以便使用扫描方法读取。信息技术
// 成功时返回true，如果没有下一个结果行或错误，则返回false
// 在准备过程中发生的。应咨询Err以区分
// 这两起案件。
// None
// 每次调用Scan（即使是第一次）之前都必须调用Next。
func (rs *Rows) Next() bool {
	var doClose, ok bool
	withLock(rs.closemu.RLocker(), func() {
		doClose, ok = rs.nextLocked()
	})
	if doClose {
		rs.Close()
	}
	return ok
}

func (rs *Rows) nextLocked() (doClose, ok bool) {
	if rs.closed {
		return false, false
	}

	// 在调用驱动程序接口之前锁定驱动程序连接
	// rowsi用于防止Tx同时回滚连接。
	rs.dc.Lock()
	defer rs.dc.Unlock()

	if rs.lastcols == nil {
		rs.lastcols = make([]driver.Value, len(rs.rowsi.Columns()))
	}

	rs.lasterr = rs.rowsi.Next(rs.lastcols)
	if rs.lasterr != nil {
		// 如果存在驱动程序错误，请关闭连接。
		if rs.lasterr != io.EOF {
			return true, false
		}
		nextResultSet, ok := rs.rowsi.(driver.RowsNextResultSet)
		if !ok {
			return true, false
		}
		// 驱动程序位于当前结果集的末尾。
		// 测试当前结果集之后是否还有其他结果集。
		// 只有在没有其他结果集可读取时才关闭行。
		if !nextResultSet.HasNextResultSet() {
			doClose = true
		}
		return doClose, false
	}
	return false, true
}

// NextResultSet为读取准备下一个结果集。报告是否
// 有更多的结果集，如果没有更多的结果集，则为false
// 或者如果有一个错误前进到它。应参考Err方法
// 区分这两种情况。
// None
// 调用NextResultSet后，应始终在调用之前调用下一个方法
// 扫描。如果有其他结果集，则结果中可能没有行
// 设置
func (rs *Rows) NextResultSet() bool {
	var doClose bool
	defer func() {
		if doClose {
			rs.Close()
		}
	}()
	rs.closemu.RLock()
	defer rs.closemu.RUnlock()

	if rs.closed {
		return false
	}

	rs.lastcols = nil
	nextResultSet, ok := rs.rowsi.(driver.RowsNextResultSet)
	if !ok {
		doClose = true
		return false
	}

	// 在调用驱动程序接口之前锁定驱动程序连接
	// rowsi用于防止Tx同时回滚连接。
	rs.dc.Lock()
	defer rs.dc.Unlock()

	rs.lasterr = nextResultSet.NextResultSet()
	if rs.lasterr != nil {
		doClose = true
		return false
	}
	return true
}

// Err返回迭代期间遇到的错误（如果有）。
// Err可以在显式或隐式关闭后调用。
func (rs *Rows) Err() error {
	rs.closemu.RLock()
	defer rs.closemu.RUnlock()
	return rs.lasterrOrErrLocked(nil)
}

var errRowsClosed = errors.New("sql: Rows are closed")
var errNoRows = errors.New("sql: no Rows available")

// Columns返回列名。
// 如果行关闭，列将返回错误。
func (rs *Rows) Columns() ([]string, error) {
	rs.closemu.RLock()
	defer rs.closemu.RUnlock()
	if rs.closed {
		return nil, rs.lasterrOrErrLocked(errRowsClosed)
	}
	if rs.rowsi == nil {
		return nil, rs.lasterrOrErrLocked(errNoRows)
	}
	rs.dc.Lock()
	defer rs.dc.Unlock()

	return rs.rowsi.Columns(), nil
}

// ColumnTypes返回列信息，如列类型、长度、，
// 并且可以为空。某些驾驶员可能无法提供某些信息。
func (rs *Rows) ColumnTypes() ([]*ColumnType, error) {
	rs.closemu.RLock()
	defer rs.closemu.RUnlock()
	if rs.closed {
		return nil, rs.lasterrOrErrLocked(errRowsClosed)
	}
	if rs.rowsi == nil {
		return nil, rs.lasterrOrErrLocked(errNoRows)
	}
	rs.dc.Lock()
	defer rs.dc.Unlock()

	return rowsColumnInfoSetupConnLocked(rs.rowsi), nil
}

// ColumnType包含列的名称和类型。
type ColumnType struct {
	name string

	hasNullable       bool
	hasLength         bool
	hasPrecisionScale bool

	nullable     bool
	length       int64
	databaseType string
	precision    int64
	scale        int64
	scanType     reflect.Type
}

// Name返回列的名称或别名。
func (ci *ColumnType) Name() string {
	return ci.name
}

// Length返回可变长度列类型的列类型长度，如
// 作为文本和二进制字段类型。如果类型长度是无界的，则该值将
// 为math.MaxInt64（任何数据库限制仍将适用）。
// 如果列类型不是可变长度，例如int，或者不受支持
// 由驱动程序确定为假。
func (ci *ColumnType) Length() (length int64, ok bool) {
	return ci.length, ci.hasLength
}

// DecimalSize返回十进制类型的小数位数和精度。
// 如果不适用或不受支持，则“确定”为假。
func (ci *ColumnType) DecimalSize() (precision, scale int64, ok bool) {
	return ci.precision, ci.scale, ci.hasPrecisionScale
}

// ScanType返回适合使用Rows.Scan扫描的Go类型。
// 如果驱动程序不支持此属性，ScanType将返回
// 空接口的类型。
func (ci *ColumnType) ScanType() reflect.Type {
	return ci.scanType
}

// Nullable报告列是否可以为null。
// 如果驱动程序不支持此属性，“确定”将为false。
func (ci *ColumnType) Nullable() (nullable, ok bool) {
	return ci.nullable, ci.hasNullable
}

// DatabaseTypeName返回列类型的数据库系统名称。如果是空的
// 返回字符串，则不支持驱动程序类型名称。
// 有关驱动程序数据类型的列表，请参阅驱动程序文档。长度说明符
// 不包括在内。
// 常见的类型名称包括“VARCHAR”、“TEXT”、“NVARCHAR”、“DECIMAL”、“BOOL”，
// “INT”和“BIGINT”。
func (ci *ColumnType) DatabaseTypeName() string {
	return ci.databaseType
}

func rowsColumnInfoSetupConnLocked(rowsi driver.Rows) []*ColumnType {
	names := rowsi.Columns()

	list := make([]*ColumnType, len(names))
	for i := range list {
		ci := &ColumnType{
			name: names[i],
		}
		list[i] = ci

		if prop, ok := rowsi.(driver.RowsColumnTypeScanType); ok {
			ci.scanType = prop.ColumnTypeScanType(i)
		} else {
			ci.scanType = reflect.TypeOf(new(interface{})).Elem()
		}
		if prop, ok := rowsi.(driver.RowsColumnTypeDatabaseTypeName); ok {
			ci.databaseType = prop.ColumnTypeDatabaseTypeName(i)
		}
		if prop, ok := rowsi.(driver.RowsColumnTypeLength); ok {
			ci.length, ci.hasLength = prop.ColumnTypeLength(i)
		}
		if prop, ok := rowsi.(driver.RowsColumnTypeNullable); ok {
			ci.nullable, ci.hasNullable = prop.ColumnTypeNullable(i)
		}
		if prop, ok := rowsi.(driver.RowsColumnTypePrecisionScale); ok {
			ci.precision, ci.scale, ci.hasPrecisionScale = prop.ColumnTypePrecisionScale(i)
		}
	}
	return list
}

// 扫描将当前行中的列复制到指定的值中
// 在目的地。dest中的值数必须与
// 行中的列数。
// None
// 扫描将从数据库读取的列转换为以下列
// sql包提供的常见Go类型和特殊类型：
// None
// *串
// *[]字节
// *整数、*int8、*int16、*int32、*int64
// *uint，*uint8，*uint16，*uint32，*uint64
// *布尔
// *浮动32，*浮动64
// *接口{}
// *原始字节
// *行（光标值）
// 任何类型的扫描仪（参见扫描仪文档）
// None
// 在最简单的情况下，如果源中的值的类型
// 列是整数、布尔或字符串类型T，而dest是*T类型，
// 扫描只是通过指针分配值。
// None
// 扫描还可以在字符串和数字类型之间转换，只要没有
// 信息将会丢失。而扫描将字符串化所有数字
// 从数字数据库列扫描到*字符串，扫描到
// 检查数值类型是否溢出。例如，带有
// 值300或值为“300”的字符串可以扫描到uint16，但
// 虽然float64（255）或“255”可以扫描到
// uint8。一个例外是扫描一些浮点数到
// 字符串化时，字符串可能会丢失信息。一般来说，扫描
// 浮点列转换为*float64。
// None
// 如果dest参数的类型为*[]字节，Scan会在该参数中保存一个
// 相应数据的副本。副本归调用方所有，并且
// 可以修改并无限期保留。复制可以通过以下方式避免：
// 改为使用*RawBytes类型的参数；请参阅文档
// 对于RawBytes，请查看对其使用的限制。
// None
// 如果参数的类型为*接口{}，则扫描将复制该值
// 由底层驱动程序提供，无需转换。扫描时
// 从[]字节类型的源值到*接口{}，一个
// 生成切片，调用方拥有结果。
// None
// 时间类型的源值。可以将时间扫描为时间类型的值
// *time、*接口{}、*字符串或*[]字节。当转换为
// 使用后两种，time.rfc339nano。
// None
// bool类型的源值可以扫描为*bool类型，
// *接口{}、*字符串、*[]字节或*RawBytes。
// None
// 对于扫描到*bool，源可以是true、false、1、0或
// 可由strconv.ParseBool解析的字符串输入。
// None
// 扫描还可以转换查询返回的游标，例如
// “从dual中选择光标（从my_表中选择*）”进入
// *可以从中扫描自身的行值。父母
// 如果父*行关闭，select查询将关闭任何游标*行。
// None
// 如果实现Scanner的任何第一个参数返回错误，
// 该错误将被包装在返回的错误中
func (rs *Rows) Scan(dest ...interface{}) error {
	rs.closemu.RLock()

	if rs.lasterr != nil && rs.lasterr != io.EOF {
		rs.closemu.RUnlock()
		return rs.lasterr
	}
	if rs.closed {
		err := rs.lasterrOrErrLocked(errRowsClosed)
		rs.closemu.RUnlock()
		return err
	}
	rs.closemu.RUnlock()

	if rs.lastcols == nil {
		return errors.New("sql: Scan called without calling Next")
	}
	if len(dest) != len(rs.lastcols) {
		return fmt.Errorf("sql: expected %d destination arguments in Scan, not %d", len(rs.lastcols), len(dest))
	}
	for i, sv := range rs.lastcols {
		err := convertAssignRows(dest[i], sv, rs)
		if err != nil {
			return fmt.Errorf(`sql: Scan error on column index %d, name %q: %w`, i, rs.rowsi.Columns()[i], err)
		}
	}
	return nil
}

// rowsCloseHook返回一个函数，以便测试可以安装
// 钩住一个只测试的互斥锁。
var rowsCloseHook = func() func(*Rows, *error) { return nil }

// Close关闭行，防止进一步枚举。如果调用Next
// 返回false，并且没有进一步的结果集，
// 行将自动关闭，只需检查
// 错误的结果。Close是幂等的，不影响Err的结果。
func (rs *Rows) Close() error {
	return rs.close(nil)
}

func (rs *Rows) close(err error) error {
	rs.closemu.Lock()
	defer rs.closemu.Unlock()

	if rs.closed {
		return nil
	}
	rs.closed = true

	if rs.lasterr == nil {
		rs.lasterr = err
	}

	withLock(rs.dc, func() {
		err = rs.rowsi.Close()
	})
	if fn := rowsCloseHook(); fn != nil {
		fn(rs, &err)
	}
	if rs.cancel != nil {
		rs.cancel()
	}

	if rs.closeStmt != nil {
		rs.closeStmt.Close()
	}
	rs.releaseConn(err)
	return err
}

// Row是调用QueryRow以选择单个行的结果。
type Row struct {
	// 其中一项为非零：
	err  error // 容易链接的延迟错误
	rows *Rows
}

// 扫描将匹配行中的列复制到值中
// 由dest指向。请参阅有关行的文档。有关详细信息，请扫描。
// 如果有多行与查询匹配，
// 扫描使用第一行并丢弃其余行。如果没有行匹配
// 查询Scan返回ErrNoRows。
func (r *Row) Scan(dest ...interface{}) error {
	if r.err != nil {
		return r.err
	}

	// 托多（布拉德菲茨）：现在我们需要在防守上克隆所有人
	// []驱动程序返回的字节（不允许
	// *行中的RawBytes.Scan），因为我们即将关闭
	// 当我们从此函数返回时，延迟中的行。
	// 与driver.Next（…）接口的约定是
	// 可以将片返回到只读临时内存中
	// 仅在下次扫描/关闭前有效。但要做的是
	// 对于很多司机来说，这份复印件是不必要的。我们
	// 应为驱动程序提供一个可选接口
	// 实现说：“别担心，我返回的[]字节
	// “从下一步开始”将不会再次修改。”（例如，如果
	// 他们是从网络上获得的）但现在我们
	// 不在乎。
	defer r.rows.Close()
	for _, dp := range dest {
		if _, ok := dp.(*RawBytes); ok {
			return errors.New("sql: RawBytes isn't allowed on Row.Scan")
		}
	}

	if !r.rows.Next() {
		if err := r.rows.Err(); err != nil {
			return err
		}
		return ErrNoRows
	}
	err := r.rows.Scan(dest...)
	if err != nil {
		return err
	}
	// 确保查询可以处理到完成，没有错误。
	return r.rows.Close()
}

// Err提供了一种包装包以检查
// 查询错误而不调用扫描。
// Err返回运行查询时遇到的错误（如果有）。
// 如果此错误不是nil，则扫描时也会返回此错误。
func (r *Row) Err() error {
	return r.err
}

// 结果汇总了已执行的SQL命令。
type Result interface {
	// LastInsertId返回数据库生成的整数
	// 响应命令。通常，这将来自
	// 插入新行时的“自动增量”列。不是全部
	// 数据库支持此功能，以及此类功能的语法
	// 声明各不相同。
	LastInsertId() (int64, error)

	// RowsAffected返回受影响的行数
	// 更新、插入或删除。不是每个数据库都有
	// 司机可能会支持这一点。
	RowsAffected() (int64, error)
}

type driverResult struct {
	sync.Locker // 驾驶舱
	resi        driver.Result
}

func (dr driverResult) LastInsertId() (int64, error) {
	dr.Lock()
	defer dr.Unlock()
	return dr.resi.LastInsertId()
}

func (dr driverResult) RowsAffected() (int64, error) {
	dr.Lock()
	defer dr.Unlock()
	return dr.resi.RowsAffected()
}

func stack() string {
	var buf [2 << 10]byte
	return string(buf[:runtime.Stack(buf[:], false)])
}

// withLock在按住lk的同时运行。
func withLock(lk sync.Locker, fn func()) {
	lk.Lock()
	defer lk.Unlock() // 以防新生力量恐慌
	fn()
}
